@optimystic/db-core 1.9.0 → 1.10.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/dist/src/cohort-topic/addressing.d.ts +46 -6
- package/dist/src/cohort-topic/addressing.d.ts.map +1 -1
- package/dist/src/cohort-topic/addressing.js +58 -18
- package/dist/src/cohort-topic/addressing.js.map +1 -1
- package/dist/src/cohort-topic/member-engine.d.ts +21 -1
- package/dist/src/cohort-topic/member-engine.d.ts.map +1 -1
- package/dist/src/cohort-topic/member-engine.js +39 -9
- package/dist/src/cohort-topic/member-engine.js.map +1 -1
- package/dist/src/cohort-topic/membership/publisher.js +1 -1
- package/dist/src/cohort-topic/membership/publisher.js.map +1 -1
- package/dist/src/cohort-topic/membership/source.d.ts +4 -0
- package/dist/src/cohort-topic/membership/source.d.ts.map +1 -1
- package/dist/src/cohort-topic/membership/source.js +4 -0
- package/dist/src/cohort-topic/membership/source.js.map +1 -1
- package/dist/src/cohort-topic/membership/verifier.d.ts +51 -9
- package/dist/src/cohort-topic/membership/verifier.d.ts.map +1 -1
- package/dist/src/cohort-topic/membership/verifier.js +138 -46
- package/dist/src/cohort-topic/membership/verifier.js.map +1 -1
- package/dist/src/cohort-topic/ports.d.ts +85 -14
- package/dist/src/cohort-topic/ports.d.ts.map +1 -1
- package/dist/src/cohort-topic/ports.js +1 -1
- package/dist/src/cohort-topic/ports.js.map +1 -1
- package/dist/src/cohort-topic/promotion.d.ts +3 -2
- package/dist/src/cohort-topic/promotion.d.ts.map +1 -1
- package/dist/src/cohort-topic/promotion.js +15 -3
- package/dist/src/cohort-topic/promotion.js.map +1 -1
- package/dist/src/cohort-topic/registration/renewal.d.ts +26 -5
- package/dist/src/cohort-topic/registration/renewal.d.ts.map +1 -1
- package/dist/src/cohort-topic/registration/renewal.js +71 -21
- package/dist/src/cohort-topic/registration/renewal.js.map +1 -1
- package/dist/src/cohort-topic/service.d.ts +34 -2
- package/dist/src/cohort-topic/service.d.ts.map +1 -1
- package/dist/src/cohort-topic/service.js +86 -28
- package/dist/src/cohort-topic/service.js.map +1 -1
- package/dist/src/cohort-topic/sig/payloads.d.ts +5 -1
- package/dist/src/cohort-topic/sig/payloads.d.ts.map +1 -1
- package/dist/src/cohort-topic/sig/payloads.js +6 -1
- package/dist/src/cohort-topic/sig/payloads.js.map +1 -1
- package/dist/src/cohort-topic/sig/threshold.d.ts +29 -4
- package/dist/src/cohort-topic/sig/threshold.d.ts.map +1 -1
- package/dist/src/cohort-topic/sig/threshold.js +39 -7
- package/dist/src/cohort-topic/sig/threshold.js.map +1 -1
- package/dist/src/cohort-topic/walk.d.ts +19 -4
- package/dist/src/cohort-topic/walk.d.ts.map +1 -1
- package/dist/src/cohort-topic/walk.js +29 -6
- package/dist/src/cohort-topic/walk.js.map +1 -1
- package/dist/src/cohort-topic/willingness.d.ts +17 -1
- package/dist/src/cohort-topic/willingness.d.ts.map +1 -1
- package/dist/src/cohort-topic/willingness.js +18 -3
- package/dist/src/cohort-topic/willingness.js.map +1 -1
- package/dist/src/cohort-topic/wire/index.d.ts +1 -1
- package/dist/src/cohort-topic/wire/index.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/index.js +1 -1
- package/dist/src/cohort-topic/wire/index.js.map +1 -1
- package/dist/src/cohort-topic/wire/payloads.d.ts +14 -0
- package/dist/src/cohort-topic/wire/payloads.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/payloads.js +20 -0
- package/dist/src/cohort-topic/wire/payloads.js.map +1 -1
- package/dist/src/cohort-topic/wire/primitives.d.ts +8 -0
- package/dist/src/cohort-topic/wire/primitives.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/primitives.js +24 -4
- package/dist/src/cohort-topic/wire/primitives.js.map +1 -1
- package/dist/src/cohort-topic/wire/types.d.ts +37 -0
- package/dist/src/cohort-topic/wire/types.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/validate.d.ts +9 -1
- package/dist/src/cohort-topic/wire/validate.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/validate.js +23 -4
- package/dist/src/cohort-topic/wire/validate.js.map +1 -1
- package/dist/src/reactivity/config.d.ts +9 -10
- package/dist/src/reactivity/config.d.ts.map +1 -1
- package/dist/src/reactivity/config.js +9 -9
- package/dist/src/reactivity/config.js.map +1 -1
- package/dist/src/reactivity/index.d.ts +4 -3
- package/dist/src/reactivity/index.d.ts.map +1 -1
- package/dist/src/reactivity/index.js +4 -3
- package/dist/src/reactivity/index.js.map +1 -1
- package/dist/src/reactivity/rotation.d.ts +73 -57
- package/dist/src/reactivity/rotation.d.ts.map +1 -1
- package/dist/src/reactivity/rotation.js +54 -54
- package/dist/src/reactivity/rotation.js.map +1 -1
- package/dist/src/reactivity/subscription.d.ts +12 -9
- package/dist/src/reactivity/subscription.d.ts.map +1 -1
- package/dist/src/reactivity/subscription.js +9 -6
- package/dist/src/reactivity/subscription.js.map +1 -1
- package/dist/src/reactivity/topic-anchor.d.ts +36 -31
- package/dist/src/reactivity/topic-anchor.d.ts.map +1 -1
- package/dist/src/reactivity/topic-anchor.js +41 -39
- package/dist/src/reactivity/topic-anchor.js.map +1 -1
- package/dist/src/reactivity/verify.d.ts +26 -9
- package/dist/src/reactivity/verify.d.ts.map +1 -1
- package/dist/src/reactivity/verify.js +26 -11
- package/dist/src/reactivity/verify.js.map +1 -1
- package/dist/src/reactivity/wire.d.ts +1 -1
- package/dist/src/reactivity/wire.d.ts.map +1 -1
- package/dist/src/transactor/change-notifier.d.ts +1 -1
- package/package.json +1 -1
- package/src/cohort-topic/addressing.ts +83 -23
- package/src/cohort-topic/member-engine.ts +77 -8
- package/src/cohort-topic/membership/publisher.ts +1 -1
- package/src/cohort-topic/membership/source.ts +4 -0
- package/src/cohort-topic/membership/verifier.ts +169 -51
- package/src/cohort-topic/ports.ts +87 -15
- package/src/cohort-topic/promotion.ts +15 -3
- package/src/cohort-topic/registration/renewal.ts +87 -24
- package/src/cohort-topic/service.ts +157 -35
- package/src/cohort-topic/sig/payloads.ts +7 -2
- package/src/cohort-topic/sig/threshold.ts +41 -7
- package/src/cohort-topic/walk.ts +46 -9
- package/src/cohort-topic/willingness.ts +34 -3
- package/src/cohort-topic/wire/index.ts +1 -0
- package/src/cohort-topic/wire/payloads.ts +21 -0
- package/src/cohort-topic/wire/primitives.ts +26 -4
- package/src/cohort-topic/wire/types.ts +37 -0
- package/src/cohort-topic/wire/validate.ts +26 -3
- package/src/reactivity/config.ts +10 -10
- package/src/reactivity/index.ts +4 -3
- package/src/reactivity/rotation.ts +86 -78
- package/src/reactivity/subscription.ts +12 -9
- package/src/reactivity/topic-anchor.ts +42 -45
- package/src/reactivity/verify.ts +36 -17
- package/src/reactivity/wire.ts +1 -1
- package/src/transactor/change-notifier.ts +1 -1
package/src/cohort-topic/walk.ts
CHANGED
|
@@ -25,6 +25,11 @@
|
|
|
25
25
|
* `afterMs` — which begins again at `d_max`, decorrelating retries across the ring (§Anti-flood
|
|
26
26
|
* claim 4: never re-hit the declined coord immediately).
|
|
27
27
|
*
|
|
28
|
+
* **Root-placed topics.** A walk given a `rootKey` (§Tier addressing → Root placement at a routing key)
|
|
29
|
+
* stamps it on every frame it builds and addresses its tier-0 step at `H(rootKey)` — delivered through
|
|
30
|
+
* {@link ITopicRouter.routeToRoot} when the router has it, else `routeAndAct` on the root key. Every other
|
|
31
|
+
* step, reply and back-off rule above is unchanged.
|
|
32
|
+
*
|
|
28
33
|
* This module is FRET-free: it drives the {@link ITopicRouter} port (db-p2p binds it to FRET's
|
|
29
34
|
* `RouteAndMaybeAct` / direct dial) and the {@link TierAddressing} math, and delegates building +
|
|
30
35
|
* signing the {@link RegisterV1} to the injected {@link RegisterMessageFactory} (participant identity
|
|
@@ -49,6 +54,8 @@ export interface AcceptedWalkOutcome {
|
|
|
49
54
|
* probe carries a distinct correlationId; this is the one the cohort admitted.
|
|
50
55
|
*/
|
|
51
56
|
readonly correlationId: string;
|
|
57
|
+
/** The tree tier `d` of the register frame the cohort accepted — where the registration landed. */
|
|
58
|
+
readonly treeTier: number;
|
|
52
59
|
}
|
|
53
60
|
|
|
54
61
|
/**
|
|
@@ -84,6 +91,7 @@ export interface RegisterMessageFactory {
|
|
|
84
91
|
* (§Anti-DoS — a follow-on is gated identically to a bootstrap) via the injected builder seam before
|
|
85
92
|
* signing — keyed off `bootstrap`/`followOn`, so no extra parameter is needed (the walk decides both
|
|
86
93
|
* internally, not the application). `bootstrap`, `followOn`, and `probe` are mutually exclusive.
|
|
94
|
+
* A `rootKey` is stamped on the frame as `RegisterV1.rootKey` **before** signing, at every tier.
|
|
87
95
|
*/
|
|
88
96
|
build(params: {
|
|
89
97
|
topicId: Uint8Array;
|
|
@@ -95,9 +103,19 @@ export interface RegisterMessageFactory {
|
|
|
95
103
|
/** Read-only lookup probe: the factory stamps `RegisterV1.probe` and never mints cold-start evidence. */
|
|
96
104
|
probe: boolean;
|
|
97
105
|
appPayload?: Uint8Array;
|
|
106
|
+
/** Root key of a root-placed topic; absent for the default addressing. */
|
|
107
|
+
rootKey?: Uint8Array;
|
|
98
108
|
}): Promise<RegisterV1>;
|
|
99
109
|
}
|
|
100
110
|
|
|
111
|
+
/** Per-walk options for {@link WalkEngine.register}. */
|
|
112
|
+
export interface WalkOptions {
|
|
113
|
+
/** Read-only lookup: classify without admitting, and never cold-start. */
|
|
114
|
+
readonly probe?: boolean;
|
|
115
|
+
/** Root key of a root-placed topic: the walk's tier-0 step targets `H(rootKey)` and every frame carries the key. */
|
|
116
|
+
readonly rootKey?: Uint8Array;
|
|
117
|
+
}
|
|
118
|
+
|
|
101
119
|
export interface WalkConfig {
|
|
102
120
|
/** Cohort size requested from the router (`wantK`). Default 16. */
|
|
103
121
|
wantK?: number;
|
|
@@ -139,9 +157,9 @@ export interface WalkEngine {
|
|
|
139
157
|
* redirects outward. Resolves with the terminal {@link WalkOutcome}. With `opts.probe` the walk is a
|
|
140
158
|
* **read-only lookup**: identical routing discipline, but the terminal cohort classifies rather than
|
|
141
159
|
* admits and the root `no_state` branch backs off instead of issuing a `bootstrap: true` cold-start
|
|
142
|
-
* (a probe never instantiates a cold root).
|
|
160
|
+
* (a probe never instantiates a cold root). With `opts.rootKey` the topic is root-placed.
|
|
143
161
|
*/
|
|
144
|
-
register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?:
|
|
162
|
+
register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?: WalkOptions): Promise<WalkOutcome>;
|
|
145
163
|
}
|
|
146
164
|
|
|
147
165
|
/**
|
|
@@ -172,10 +190,11 @@ class RouterWalkEngine implements WalkEngine {
|
|
|
172
190
|
this.maxMessageBytes = cfg.maxMessageBytes;
|
|
173
191
|
}
|
|
174
192
|
|
|
175
|
-
async register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?:
|
|
193
|
+
async register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?: WalkOptions): Promise<WalkOutcome> {
|
|
176
194
|
const dMax = this.deps.dmax.dMax();
|
|
177
195
|
const maxSteps = this.configuredMaxSteps ?? 2 * (dMax + 2) + this.maxMemberRetries + 8;
|
|
178
196
|
const probe = opts?.probe ?? false;
|
|
197
|
+
const rootKey = opts?.rootKey;
|
|
179
198
|
|
|
180
199
|
let d = dMax;
|
|
181
200
|
let bootstrap = false;
|
|
@@ -200,21 +219,18 @@ class RouterWalkEngine implements WalkEngine {
|
|
|
200
219
|
return { kind: "retry_later", afterMs: backoffRetryMs(0) };
|
|
201
220
|
}
|
|
202
221
|
|
|
203
|
-
const reg = await this.deps.factory.build({ topicId, tier, treeTier: d, bootstrap, followOn, probe, appPayload });
|
|
222
|
+
const reg = await this.deps.factory.build({ topicId, tier, treeTier: d, bootstrap, followOn, probe, appPayload, rootKey });
|
|
204
223
|
const activity = encodeCohortMessage(reg, this.maxMessageBytes);
|
|
205
224
|
const raw = dialTarget !== undefined
|
|
206
225
|
? await this.deps.router.dialMember(dialTarget, activity)
|
|
207
|
-
: await this.
|
|
208
|
-
wantK: this.wantK,
|
|
209
|
-
minSigs: this.minSigs,
|
|
210
|
-
});
|
|
226
|
+
: await this.routeToTier(d, topicId, rootKey, activity);
|
|
211
227
|
const reply = decodeRegisterReplyV1(raw, this.maxMessageBytes);
|
|
212
228
|
|
|
213
229
|
switch (reply.result) {
|
|
214
230
|
case "accepted": {
|
|
215
231
|
// Surface the accepted probe's correlationId so the participant's renewals can echo it
|
|
216
232
|
// (RenewV1 correlationId "matches original RegisterV1"). `reg` is the frame just admitted.
|
|
217
|
-
return { kind: "accepted", reply, correlationId: reg.correlationId };
|
|
233
|
+
return { kind: "accepted", reply, correlationId: reg.correlationId, treeTier: reg.treeTier };
|
|
218
234
|
}
|
|
219
235
|
case "no_state": {
|
|
220
236
|
// Step toward the root. The cohort served nothing here; no spatial sibling state.
|
|
@@ -318,6 +334,27 @@ class RouterWalkEngine implements WalkEngine {
|
|
|
318
334
|
}
|
|
319
335
|
}
|
|
320
336
|
}
|
|
337
|
+
|
|
338
|
+
/**
|
|
339
|
+
* Route one probe to the cohort at tier `d`, on that tier's route key — the router hashes it once into
|
|
340
|
+
* `coord_d`. The root of a root-placed topic goes through the router's `routeToRoot` when it has one, so
|
|
341
|
+
* the frame reaches the root group by the rule that chose it; a router without it (a mock, an older
|
|
342
|
+
* binding) routes the same frame on the root key itself, which lands at the root coordinate `H(rootKey)`.
|
|
343
|
+
*
|
|
344
|
+
* NOTE: the fallback reaches the root coordinate by ring routing, which is the root group whenever the
|
|
345
|
+
* ring's nearest peers to `H(rootKey)` are the key network's storage group for that key. `routeToRoot`
|
|
346
|
+
* exists only because the two can differ on a ring shared with another network.
|
|
347
|
+
*/
|
|
348
|
+
private routeToTier(d: number, topicId: Uint8Array, rootKey: Uint8Array | undefined, activity: Uint8Array): Promise<Uint8Array> {
|
|
349
|
+
const router = this.deps.router;
|
|
350
|
+
if (d === 0 && rootKey !== undefined && router.routeToRoot !== undefined) {
|
|
351
|
+
return router.routeToRoot(rootKey, activity);
|
|
352
|
+
}
|
|
353
|
+
return router.routeAndAct(this.deps.addressing.routeKey(d, this.deps.self, topicId, rootKey), activity, {
|
|
354
|
+
wantK: this.wantK,
|
|
355
|
+
minSigs: this.minSigs,
|
|
356
|
+
});
|
|
357
|
+
}
|
|
321
358
|
}
|
|
322
359
|
|
|
323
360
|
/** Build a {@link WalkEngine} over the injected router, addressing, `d_max`, and message factory. */
|
|
@@ -13,7 +13,9 @@
|
|
|
13
13
|
* - **{@link UnwillingCohortOutcome}** — fewer than a quorum of members are willing to serve the
|
|
14
14
|
* tier, so the cohort declines the tier entirely; the caller backs off in *time* (no spatial
|
|
15
15
|
* move — see §Why the caller doesn't walk on UnwillingCohort). The `retryAfterMs` follows the
|
|
16
|
-
* capped-doubling curve in {@link backoffRetryMs}.
|
|
16
|
+
* capped-doubling curve in {@link backoffRetryMs}. The outcome also says whether the quorum is short
|
|
17
|
+
* only for want of members that have not gossiped yet (`awaitingMembers`), which the member engine
|
|
18
|
+
* answers by holding the request for their gossip rather than declining at once.
|
|
17
19
|
*
|
|
18
20
|
* A member's *live* willingness for a tier is: its profile serves the tier, the tier's load bucket
|
|
19
21
|
* is below `overloadBucket`, **and** it is under its per-tier primary-topic budget. The coarse 1-bit
|
|
@@ -43,6 +45,14 @@ export interface UnwillingMemberOutcome {
|
|
|
43
45
|
export interface UnwillingCohortOutcome {
|
|
44
46
|
readonly kind: "unwilling_cohort";
|
|
45
47
|
readonly retryAfterMs: number;
|
|
48
|
+
/**
|
|
49
|
+
* True iff the quorum is short only because cohort members have not gossiped yet: it would be met if
|
|
50
|
+
* every member this check holds no contribution from turned out willing. A member that has gossiped
|
|
51
|
+
* *unwilling* counts as heard, so a cohort whose answers are in and short reports `false` — as does an
|
|
52
|
+
* unserviceable tier, and a check given no {@link WillingnessDeps.cohortMembers}. The cohort side may hold
|
|
53
|
+
* the request briefly for those answers instead of declining (§Cold-start instantiation).
|
|
54
|
+
*/
|
|
55
|
+
readonly awaitingMembers: boolean;
|
|
46
56
|
}
|
|
47
57
|
|
|
48
58
|
export type WillingnessOutcome = AcceptedOutcome | UnwillingMemberOutcome | UnwillingCohortOutcome;
|
|
@@ -146,6 +156,12 @@ export interface WillingnessDeps {
|
|
|
146
156
|
view: CohortView;
|
|
147
157
|
/** This member's own id, base64url (the `fromMember` key) — excluded from the sibling scan. */
|
|
148
158
|
selfMember: string;
|
|
159
|
+
/**
|
|
160
|
+
* The cohort's current members, base64url (the form {@link selfMember} and the view keys use), read at
|
|
161
|
+
* each evaluation. It tells a member that has not gossiped yet apart from one that gossiped unwilling
|
|
162
|
+
* ({@link UnwillingCohortOutcome.awaitingMembers}). Absent → no member counts as unheard.
|
|
163
|
+
*/
|
|
164
|
+
cohortMembers?: () => readonly string[];
|
|
149
165
|
/** Count of topics this member is already `primary` for at `tier` (the budget gate input). */
|
|
150
166
|
primaryTopicCount: (tier: Tier) => number;
|
|
151
167
|
/**
|
|
@@ -182,7 +198,7 @@ class GossipWillingnessCheck implements WillingnessCheck {
|
|
|
182
198
|
const tier = reg.tier as Tier;
|
|
183
199
|
if (!ALL_TIERS.includes(tier)) {
|
|
184
200
|
// An op tier outside T0..T3 is not serviceable; treat as a cohort-level decline.
|
|
185
|
-
return
|
|
201
|
+
return this.declineCohort(reg, false);
|
|
186
202
|
}
|
|
187
203
|
|
|
188
204
|
const selfWilling = this.selfLiveWilling(self, tier);
|
|
@@ -192,7 +208,7 @@ class GossipWillingnessCheck implements WillingnessCheck {
|
|
|
192
208
|
// Quorum gate (§Tier ladder): the cohort takes on tier-T duties only if a quorum of members
|
|
193
209
|
// is willing; otherwise registrations get UnwillingCohort and the caller backs off in time.
|
|
194
210
|
if (willingCount < this.quorum) {
|
|
195
|
-
return
|
|
211
|
+
return this.declineCohort(reg, willingCount + this.unheardMemberCount() >= this.quorum);
|
|
196
212
|
}
|
|
197
213
|
if (selfWilling) {
|
|
198
214
|
return { kind: "accepted" };
|
|
@@ -201,6 +217,21 @@ class GossipWillingnessCheck implements WillingnessCheck {
|
|
|
201
217
|
return { kind: "unwilling_member", candidateMembers: siblings.map((m) => b64urlToBytes(m)) };
|
|
202
218
|
}
|
|
203
219
|
|
|
220
|
+
private declineCohort(reg: RegisterV1, awaitingMembers: boolean): UnwillingCohortOutcome {
|
|
221
|
+
return { kind: "unwilling_cohort", retryAfterMs: backoffRetryMs(this.attempts(reg), this.backoff), awaitingMembers };
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/** Cohort members other than self this check holds no gossiped contribution from. */
|
|
225
|
+
private unheardMemberCount(): number {
|
|
226
|
+
const unheard = new Set<string>();
|
|
227
|
+
for (const member of this.deps.cohortMembers?.() ?? []) {
|
|
228
|
+
if (member !== this.deps.selfMember && this.deps.view.get(member) === undefined) {
|
|
229
|
+
unheard.add(member);
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
return unheard.size;
|
|
233
|
+
}
|
|
234
|
+
|
|
204
235
|
/** Live willingness of *this* member for `tier`: profile ∧ load-under-threshold ∧ under budget. */
|
|
205
236
|
private selfLiveWilling(self: NodeProfile, tier: Tier): boolean {
|
|
206
237
|
return (
|
|
@@ -13,6 +13,12 @@
|
|
|
13
13
|
* `followOn`→`false`, `appPayload`→`null`, `bootstrapEvidence`→`null` with an empty string treated as
|
|
14
14
|
* absent, `reattach`→`false`, `withdraw`→`false`) so an absent optional and a present-but-default
|
|
15
15
|
* optional can never disagree across the wire round-trip.
|
|
16
|
+
*
|
|
17
|
+
* The root-placement fields (`RegisterV1.rootKey`, `CohortGossipV1.rootPlaced`) are the exception: each
|
|
18
|
+
* is appended to its image **only when present**, with no placeholder. A frame without the field
|
|
19
|
+
* therefore signs exactly the bytes it signed before the field existed, and the two forms cannot be
|
|
20
|
+
* confused — they differ in array length, and neither field has a "present but default" spelling (the
|
|
21
|
+
* validator rejects an empty `rootKey` and a `rootPlaced` other than `true`).
|
|
16
22
|
*/
|
|
17
23
|
|
|
18
24
|
import type { CohortGossipV1, RegisterV1, RenewV1 } from "./types.js";
|
|
@@ -53,9 +59,21 @@ export function registerSigningPayload(body: RegisterSignable): Uint8Array {
|
|
|
53
59
|
// signer (participant) + verifier (db-p2p cohort) agree byte-for-byte. Safe to append: no register
|
|
54
60
|
// signatures are persisted (each is recomputed per verify), so there is no cross-version image concern.
|
|
55
61
|
body.followOn ?? false,
|
|
62
|
+
// The root key of a root-placed topic, appended only when present: a frame without one keeps the
|
|
63
|
+
// image above byte-for-byte, and stripping or swapping the key changes the image and fails verify.
|
|
64
|
+
...presentOnly(body.rootKey),
|
|
56
65
|
]));
|
|
57
66
|
}
|
|
58
67
|
|
|
68
|
+
/**
|
|
69
|
+
* `[value]` when the optional field is present, `[]` when absent — spread into a signed image for an optional
|
|
70
|
+
* element with no placeholder, so a frame without the field keeps the image it signed before the field existed.
|
|
71
|
+
* Shared with the threshold-signature images in `sig/payloads.ts`.
|
|
72
|
+
*/
|
|
73
|
+
export function presentOnly<T>(value: T | undefined): T[] {
|
|
74
|
+
return value === undefined ? [] : [value];
|
|
75
|
+
}
|
|
76
|
+
|
|
59
77
|
/** Canonical signed byte image of a `RenewV1` body (every field except `signature`). */
|
|
60
78
|
export function renewSigningPayload(body: RenewSignable): Uint8Array {
|
|
61
79
|
return utf8.encode(JSON.stringify([
|
|
@@ -86,6 +104,8 @@ export type CohortGossipSignable = Omit<CohortGossipV1, "signature">;
|
|
|
86
104
|
* the signer and the receiver (which re-derives this image from the validated frame) agree byte-for-byte.
|
|
87
105
|
* Absent optionals (`records`/`evicted`/`childLinks`/`childUnlinks`) normalize to `[]`, and `appState` to
|
|
88
106
|
* `null`. `childLinks`/`childUnlinks` are covered so a MITM cannot strip or inject a child link/unlink.
|
|
107
|
+
* `rootPlaced` is appended after `timestamp` only when present, so a gossip for a default-addressed coord
|
|
108
|
+
* keeps its image unchanged and the flag cannot be added to, or removed from, a signed frame.
|
|
89
109
|
*/
|
|
90
110
|
export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array {
|
|
91
111
|
return utf8.encode(JSON.stringify([
|
|
@@ -122,5 +142,6 @@ export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array
|
|
|
122
142
|
(g.childLinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
|
|
123
143
|
(g.childUnlinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
|
|
124
144
|
g.timestamp,
|
|
145
|
+
...presentOnly(g.rootPlaced),
|
|
125
146
|
]));
|
|
126
147
|
}
|
|
@@ -121,6 +121,22 @@ export function optBool(obj: Record<string, unknown>, key: string, what: string)
|
|
|
121
121
|
return value;
|
|
122
122
|
}
|
|
123
123
|
|
|
124
|
+
/**
|
|
125
|
+
* Return `true` when `obj[key]` is literally `true`, `undefined` when absent; throw on anything else —
|
|
126
|
+
* `false` included. For a presence flag whose only legal value is `true`, so an absent flag and a
|
|
127
|
+
* `false` one cannot be two spellings of the same thing in a signed image.
|
|
128
|
+
*/
|
|
129
|
+
export function optTrue(obj: Record<string, unknown>, key: string, what: string): true | undefined {
|
|
130
|
+
const value = obj[key];
|
|
131
|
+
if (value === undefined) {
|
|
132
|
+
return undefined;
|
|
133
|
+
}
|
|
134
|
+
if (value !== true) {
|
|
135
|
+
failWire(`${what}: field "${key}" must be true when present`);
|
|
136
|
+
}
|
|
137
|
+
return true;
|
|
138
|
+
}
|
|
139
|
+
|
|
124
140
|
/**
|
|
125
141
|
* Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. Reads and
|
|
126
142
|
* finite-checks the field itself (via {@link reqFiniteNumber}) so callers pass the object + key rather
|
|
@@ -180,16 +196,22 @@ export function b64urlField(value: string, key: string, what: string): string {
|
|
|
180
196
|
return value;
|
|
181
197
|
}
|
|
182
198
|
|
|
183
|
-
/** Assert a base64url string decodes cleanly to
|
|
184
|
-
export function
|
|
199
|
+
/** Assert a base64url string decodes cleanly to between `min` and `max` bytes inclusive; returns it unchanged. */
|
|
200
|
+
export function b64urlBoundedLen(value: string, key: string, min: number, max: number, what: string): string {
|
|
185
201
|
let bytes: Uint8Array;
|
|
186
202
|
try {
|
|
187
203
|
bytes = b64urlToBytes(value);
|
|
188
204
|
} catch {
|
|
189
205
|
return failWire(`${what}: field "${key}" is not valid base64url`);
|
|
190
206
|
}
|
|
191
|
-
if (bytes.length
|
|
192
|
-
|
|
207
|
+
if (bytes.length < min || bytes.length > max) {
|
|
208
|
+
const expected = min === max ? `${min}` : `${min}..${max}`;
|
|
209
|
+
failWire(`${what}: field "${key}" must decode to ${expected} bytes, got ${bytes.length}`);
|
|
193
210
|
}
|
|
194
211
|
return value;
|
|
195
212
|
}
|
|
213
|
+
|
|
214
|
+
/** Assert a base64url string decodes cleanly to exactly `len` bytes; returns it unchanged. */
|
|
215
|
+
export function b64urlFixedLen(value: string, key: string, len: number, what: string): string {
|
|
216
|
+
return b64urlBoundedLen(value, key, len, len, what);
|
|
217
|
+
}
|
|
@@ -67,6 +67,16 @@ export interface RegisterV1 {
|
|
|
67
67
|
* absent (it normalizes to the same signed-image placeholder as an absent field).
|
|
68
68
|
*/
|
|
69
69
|
bootstrapEvidence?: string;
|
|
70
|
+
/**
|
|
71
|
+
* Root key of a **root-placed** topic, base64url of the raw key bytes (1..`MAX_ROOT_KEY_BYTES`) — for
|
|
72
|
+
* reactivity, the routing key of the collection's log tail block. When present the topic's tier-0
|
|
73
|
+
* coordinate is `H(rootKey)` instead of `H(0x00 ‖ topicId)` (§Tier addressing → Root placement at a
|
|
74
|
+
* routing key). Set on **every** tier's frame of such a topic, not only the root's: tiers `d ≥ 1` keep
|
|
75
|
+
* their usual coordinate, but a tier-1 cohort needs the key to find its parent. Absent for every topic
|
|
76
|
+
* that uses the default addressing. Covered by `signature` (appended to `registerSigningPayload` only
|
|
77
|
+
* when present) so a MITM cannot strip or swap it.
|
|
78
|
+
*/
|
|
79
|
+
rootKey?: string;
|
|
70
80
|
/** Unix ms. */
|
|
71
81
|
timestamp: number;
|
|
72
82
|
/** 16 random bytes, base64url. */
|
|
@@ -197,6 +207,13 @@ export interface ChildLinkV1 {
|
|
|
197
207
|
signers: string[];
|
|
198
208
|
/** Child cohort epoch, 32 bytes base64url (the epoch the threshold sig was collected under). */
|
|
199
209
|
cohortEpoch: string;
|
|
210
|
+
/**
|
|
211
|
+
* Root key of a root-placed topic (see {@link RegisterV1.rootKey}), base64url. Set by a **tier-1** child
|
|
212
|
+
* of such a topic so its parent — the root, which sits at `H(rootKey)` rather than `coord_0(topicId)` —
|
|
213
|
+
* can recompute its own served coord when binding the parent-child relationship. Absent otherwise.
|
|
214
|
+
* Covered by the child cohort's threshold signature (`childLinkSigningPayload`, only when present).
|
|
215
|
+
*/
|
|
216
|
+
rootKey?: string;
|
|
200
217
|
}
|
|
201
218
|
|
|
202
219
|
/** Parent → child ack. `linked` flips the child `awaiting_parent → serving`; `rejected` keeps it awaiting. */
|
|
@@ -363,6 +380,13 @@ export interface CohortGossipV1 {
|
|
|
363
380
|
* converges to unlinked regardless of arrival order.
|
|
364
381
|
*/
|
|
365
382
|
childUnlinks?: ChildLinkRefV1[];
|
|
383
|
+
/**
|
|
384
|
+
* Present (and literally `true`) when {@link coord} is the root of a root-placed topic. It tells a
|
|
385
|
+
* co-member that has no engine for the coord yet to derive the **root group** around it rather than the
|
|
386
|
+
* FRET cohort (§Tier addressing → Root placement at a routing key). Absent for every other coord.
|
|
387
|
+
* Covered by {@link signature} when present.
|
|
388
|
+
*/
|
|
389
|
+
rootPlaced?: true;
|
|
366
390
|
timestamp: number;
|
|
367
391
|
signature: string;
|
|
368
392
|
}
|
|
@@ -410,6 +434,19 @@ export interface SignRequestV1 {
|
|
|
410
434
|
cohortEpoch: string;
|
|
411
435
|
/** The already-canonical signing bytes (the requester's `sig/payloads.ts` image), base64url. */
|
|
412
436
|
payload: string;
|
|
437
|
+
/**
|
|
438
|
+
* Present (and literally `true`) when `coord` is the root of a root-placed topic, so an endorser with no
|
|
439
|
+
* engine for the coord derives the root group around it rather than the FRET cohort. The request is not
|
|
440
|
+
* itself signed, so the flag is forgeable — harmlessly: the endorser still applies its own member and
|
|
441
|
+
* epoch checks against the group it derives, and a signature set collected from a root group has at
|
|
442
|
+
* most that group's size, which falls short of the default threshold a verifier applies to a coord it
|
|
443
|
+
* was not told is root-placed (a storage group is smaller than the default `minSigs` of 14).
|
|
444
|
+
*
|
|
445
|
+
* NOTE: that last step rests on `clusterSize` (default 10) staying below `DEFAULT_MIN_SIGS` (14). A
|
|
446
|
+
* deployment whose storage groups reach 14 members loses it; sign the request (or fold the flag into the
|
|
447
|
+
* endorsed payload) before raising `clusterSize` that far.
|
|
448
|
+
*/
|
|
449
|
+
rootPlaced?: true;
|
|
413
450
|
}
|
|
414
451
|
|
|
415
452
|
/** A member's endorsement of a {@link SignRequestV1}: its peer-key signature over the request payload. */
|
|
@@ -12,6 +12,7 @@ import { DEFAULT_D_MAX_CAP } from "../dmax.js";
|
|
|
12
12
|
import {
|
|
13
13
|
assignDefined,
|
|
14
14
|
asObject,
|
|
15
|
+
b64urlBoundedLen,
|
|
15
16
|
b64urlField,
|
|
16
17
|
b64urlFixedLen,
|
|
17
18
|
COORD_BYTES,
|
|
@@ -20,6 +21,7 @@ import {
|
|
|
20
21
|
optFiniteNumber,
|
|
21
22
|
optString,
|
|
22
23
|
optStringArray,
|
|
24
|
+
optTrue,
|
|
23
25
|
reqBool,
|
|
24
26
|
reqEnum,
|
|
25
27
|
reqFiniteNumber,
|
|
@@ -79,6 +81,20 @@ function treeTier(value: number, what: string): number {
|
|
|
79
81
|
/** Correlation-id byte width (a 16-byte nonce minted per walk probe / renew). */
|
|
80
82
|
const CORRELATION_BYTES = 16;
|
|
81
83
|
|
|
84
|
+
/**
|
|
85
|
+
* Ceiling on a decoded `rootKey` (the root key of a root-placed topic). A root key is a block's routing
|
|
86
|
+
* key — the UTF-8 of its block id, 43 bytes for a generated id — so 256 leaves room for a named block
|
|
87
|
+
* while keeping a hostile frame from carrying an arbitrarily large key into a hash input and a stored
|
|
88
|
+
* per-engine field.
|
|
89
|
+
*/
|
|
90
|
+
export const MAX_ROOT_KEY_BYTES = 256;
|
|
91
|
+
|
|
92
|
+
/** Validate an optional `rootKey`: base64url of 1..{@link MAX_ROOT_KEY_BYTES} bytes, or absent. */
|
|
93
|
+
function optRootKey(obj: Record<string, unknown>, what: string): string | undefined {
|
|
94
|
+
const rootKey = optString(obj, "rootKey", what);
|
|
95
|
+
return rootKey === undefined ? undefined : b64urlBoundedLen(rootKey, "rootKey", 1, MAX_ROOT_KEY_BYTES, what);
|
|
96
|
+
}
|
|
97
|
+
|
|
82
98
|
const REGISTER_RESULTS: readonly RegisterResult[] = [
|
|
83
99
|
"accepted",
|
|
84
100
|
"no_state",
|
|
@@ -136,6 +152,7 @@ export function validateRegisterV1(value: unknown): RegisterV1 {
|
|
|
136
152
|
if (bootstrapEvidence !== undefined && bootstrapEvidence !== "") {
|
|
137
153
|
out.bootstrapEvidence = b64urlField(bootstrapEvidence, "bootstrapEvidence", what);
|
|
138
154
|
}
|
|
155
|
+
assignDefined(out, "rootKey", optRootKey(obj, what));
|
|
139
156
|
return out;
|
|
140
157
|
}
|
|
141
158
|
|
|
@@ -259,7 +276,8 @@ export function validateDemotionNoticeV1(value: unknown): DemotionNoticeV1 {
|
|
|
259
276
|
* coord is not always 32 raw bytes, e.g. a multihash-encoded peer id in tests). When `minSigs`
|
|
260
277
|
* is supplied AND the frame carries a threshold signature (`thresholdSig` non-empty), `signers.length` must
|
|
261
278
|
* be `>= minSigs`; a key-less-interim frame carries neither, so that cross-field bound is skipped. `minSigs`
|
|
262
|
-
* is optional so a bare structural decode (no quorum context) still narrows the frame.
|
|
279
|
+
* is optional so a bare structural decode (no quorum context) still narrows the frame. An optional
|
|
280
|
+
* `rootKey` (a tier-1 child of a root-placed topic) is bounded to 1..{@link MAX_ROOT_KEY_BYTES} bytes.
|
|
263
281
|
*/
|
|
264
282
|
export function validateChildLinkV1(value: unknown, minSigs?: number): ChildLinkV1 {
|
|
265
283
|
const what = "ChildLinkV1";
|
|
@@ -274,7 +292,7 @@ export function validateChildLinkV1(value: unknown, minSigs?: number): ChildLink
|
|
|
274
292
|
if (minSigs !== undefined && thresholdSig.length > 0 && signers.length < minSigs) {
|
|
275
293
|
fail(`${what}: a signed child-link needs signers.length >= ${minSigs}, got ${signers.length}`);
|
|
276
294
|
}
|
|
277
|
-
|
|
295
|
+
const out: ChildLinkV1 = {
|
|
278
296
|
v: 1,
|
|
279
297
|
topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
|
|
280
298
|
childCohortCoord: b64urlFixedLen(reqString(obj, "childCohortCoord", what), "childCohortCoord", COORD_BYTES, what),
|
|
@@ -286,6 +304,8 @@ export function validateChildLinkV1(value: unknown, minSigs?: number): ChildLink
|
|
|
286
304
|
signers,
|
|
287
305
|
cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
|
|
288
306
|
};
|
|
307
|
+
assignDefined(out, "rootKey", optRootKey(obj, what));
|
|
308
|
+
return out;
|
|
289
309
|
}
|
|
290
310
|
|
|
291
311
|
/** Validate a {@link ChildLinkReplyV1}: `result` in `linked | rejected`, optional human-readable `reason`. */
|
|
@@ -424,6 +444,7 @@ export function validateCohortGossipV1(value: unknown): CohortGossipV1 {
|
|
|
424
444
|
}
|
|
425
445
|
out.childUnlinks = childUnlinks.map(validateChildLinkRefV1);
|
|
426
446
|
}
|
|
447
|
+
assignDefined(out, "rootPlaced", optTrue(obj, "rootPlaced", what));
|
|
427
448
|
return out;
|
|
428
449
|
}
|
|
429
450
|
|
|
@@ -433,13 +454,15 @@ export function validateSignRequestV1(value: unknown): SignRequestV1 {
|
|
|
433
454
|
const what = "SignRequestV1";
|
|
434
455
|
const obj = asObject(value, what);
|
|
435
456
|
requireV1(obj, what);
|
|
436
|
-
|
|
457
|
+
const out: SignRequestV1 = {
|
|
437
458
|
v: 1,
|
|
438
459
|
kind: reqEnum(obj, "kind", SIGN_KINDS, what),
|
|
439
460
|
coord: b64urlFixedLen(reqString(obj, "coord", what), "coord", COORD_BYTES, what),
|
|
440
461
|
cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
|
|
441
462
|
payload: b64urlField(reqString(obj, "payload", what), "payload", what),
|
|
442
463
|
};
|
|
464
|
+
assignDefined(out, "rootPlaced", optTrue(obj, "rootPlaced", what));
|
|
465
|
+
return out;
|
|
443
466
|
}
|
|
444
467
|
|
|
445
468
|
export function validateSignReplyV1(value: unknown): SignReplyV1 {
|
package/src/reactivity/config.ts
CHANGED
|
@@ -6,8 +6,8 @@
|
|
|
6
6
|
* simulator fold-back ([fold-simulator-findings-into-design-docs]) can retune `W` / `dedupe_window`
|
|
7
7
|
* without touching origination, forwarding, the replay buffer, or delivery.
|
|
8
8
|
*
|
|
9
|
-
* **Simulator-validated-pending.** `W` (replay buffer depth), `dedupe_window`, `T_drain
|
|
10
|
-
*
|
|
9
|
+
* **Simulator-validated-pending.** `W` (replay buffer depth), `dedupe_window`, `T_drain` and `queue_max`
|
|
10
|
+
* are *provisional* pending the design simulator ([simulator-reactivity-replay],
|
|
11
11
|
* folded back by [fold-simulator-findings-into-design-docs]). The simulator's REVISED guidance is that `W`
|
|
12
12
|
* SHOULD become adaptive per measured commit-rate on hot collections (`W ≈ ⌈min_coverage × cps⌉`); the
|
|
13
13
|
* static `W = 256` is kept as the Edge/low-rate default. {@link resolveW} exposes that hook; the
|
|
@@ -24,6 +24,7 @@
|
|
|
24
24
|
|
|
25
25
|
import type { NodeProfile } from "../cohort-topic/tiers.js";
|
|
26
26
|
import { DEFAULT_T_REJOIN_JITTER_MS } from "../cohort-topic/antiflood/jitter.js";
|
|
27
|
+
import { EntriesPerBlock } from "../chain/chain.js";
|
|
27
28
|
|
|
28
29
|
/** Replay buffer depth (revisions per cohort, per collection). Simulator-validated-pending. */
|
|
29
30
|
export const W_DEFAULT = 256;
|
|
@@ -41,13 +42,12 @@ export const DELTA_MAX_EDGE_BYTES = 0;
|
|
|
41
42
|
export const SUBSCRIBER_TTL_CORE_MS = 90_000;
|
|
42
43
|
/** Subscriber registration TTL on an Edge node (ms), inherited from cohort-topic. */
|
|
43
44
|
export const SUBSCRIBER_TTL_EDGE_MS = 60_000;
|
|
44
|
-
/**
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
export const BLOCK_FILL_SIZE_DEFAULT = 64;
|
|
45
|
+
/**
|
|
46
|
+
* Entries per log block — drives tail rotation. The collection log starts a new tail block every
|
|
47
|
+
* `EntriesPerBlock` entries (`chain/chain.ts`), so this is that number, not a tunable of its own: the fill
|
|
48
|
+
* tracker's warm-up and filling signals fire at the commit counts the log actually rotates at.
|
|
49
|
+
*/
|
|
50
|
+
export const BLOCK_FILL_SIZE_DEFAULT = EntriesPerBlock;
|
|
51
51
|
/** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
|
|
52
52
|
export const T_DRAIN_MS = 60_000;
|
|
53
53
|
/** Transactions remaining in tail before anticipatory warm-up. Owned by the rotation ticket. */
|
|
@@ -73,7 +73,7 @@ export interface ReactivityConfig {
|
|
|
73
73
|
readonly subscriberTtlCoreMs: number;
|
|
74
74
|
/** Subscriber TTL on an Edge node (ms). */
|
|
75
75
|
readonly subscriberTtlEdgeMs: number;
|
|
76
|
-
/**
|
|
76
|
+
/** Entries per log block — drives tail rotation; the log's `EntriesPerBlock`. */
|
|
77
77
|
readonly blockFillSize: number;
|
|
78
78
|
/** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
|
|
79
79
|
readonly tDrainMs: number;
|
package/src/reactivity/index.ts
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Reactivity — push-based change notifications on the cohort-topic substrate.
|
|
3
3
|
*
|
|
4
|
-
* See `docs/reactivity.md`. This module lands the reactivity hot path — the
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* See `docs/reactivity.md`. This module lands the reactivity hot path — the collection anchor (one topic per
|
|
5
|
+
* collection, a root at the tail block's storage group), the subscribe `appPayload`, notification
|
|
6
|
+
* origination (reusing the commit cert unchanged), the forwarder receive path (verify → dedupe → buffer →
|
|
7
|
+
* forward), the `W`-entry replay ring with cohort gossip, the
|
|
7
8
|
* sliding `(revision, sigDigest)` dedupe window, and subscriber-side verify/deliver with gap detection
|
|
8
9
|
* ([reactivity-origination-replay-delivery]) — plus **recovery beyond the live stream**
|
|
9
10
|
* ([reactivity-backfill-resume-checkpoints]): the {@link ./backfill.js} RPC served from the replay ring,
|