@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
|
@@ -3,7 +3,13 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Per `docs/cohort-topic.md` §TTL and renewal and §Failure modes:
|
|
5
5
|
*
|
|
6
|
-
* - Participant pings `primary` every `ttl/3`.
|
|
6
|
+
* - Participant pings `primary` every `ttl/3`. The four replies:
|
|
7
|
+
* - `ok` — the primary touched `lastPing` and gossips it; the failure count resets.
|
|
8
|
+
* - `primary_moved` — a rotation moved the slot; the participant adopts the named primary/backups/epoch
|
|
9
|
+
* and the failure count resets.
|
|
10
|
+
* - `unknown_registration` / `withdrawn` — the member holds no record for this participant (it restarted,
|
|
11
|
+
* the record expired, a stale withdraw removed it, or gossip has not reached it yet). Counted as a failed
|
|
12
|
+
* ping, exactly like no answer: an answer from a member that does not hold the record keeps nothing alive.
|
|
7
13
|
* - Three consecutive ping failures → participant promotes `backups[0]` via a re-attach RPC: a renew
|
|
8
14
|
* carrying a **signed `reattach` flag** (no full re-registration). The backup accepts when it holds
|
|
9
15
|
* the record locally *and* is a computed backup under the current epoch — re-stamping `primary` to
|
|
@@ -13,7 +19,11 @@
|
|
|
13
19
|
* payload instead of promoting the contacted backup (ignoring a reply that points back at the dead
|
|
14
20
|
* primary). **Resolved (GROUNDING):** the participant's `cohortEpoch` hint refreshes lazily — on the
|
|
15
21
|
* *next* ping/renewal after failover, not eagerly at failover time.
|
|
16
|
-
* - All of primary + backups fail → participant re-runs lookup from `d_max` (
|
|
22
|
+
* - All of primary + backups fail → participant re-runs lookup from `d_max` (injected) and adopts where the
|
|
23
|
+
* re-walk landed — primary, backups, epoch hint and the accepted register's correlation id. A walk that is
|
|
24
|
+
* not accepted keeps the old assignment. Either way the failure count resets, so the next re-walk is at
|
|
25
|
+
* least {@link MAX_PING_FAILURES} pings away: at most one per TTL, under the cohort's per-peer register
|
|
26
|
+
* rate limit, and a one-off `unknown_registration` from replication lag clears on the next ping.
|
|
17
27
|
* - Cohort-side: evict where `now − lastPing > ttl`; eviction is gossiped so members converge.
|
|
18
28
|
*
|
|
19
29
|
* Both sides take their transport/gossip by injection so storage + sharding + TTL stay unit-testable
|
|
@@ -57,12 +67,24 @@ export interface RenewalParticipant {
|
|
|
57
67
|
/** The unsigned body of a renew/re-attach RPC; the injected signer turns it into a {@link RenewV1}. */
|
|
58
68
|
export type UnsignedRenew = Omit<RenewV1, "signature">;
|
|
59
69
|
|
|
70
|
+
/** Where a re-run register walk placed the registration; the participant adopts it in place of its own. */
|
|
71
|
+
export interface RenewalAssignment {
|
|
72
|
+
readonly primary: Uint8Array;
|
|
73
|
+
readonly backups: readonly Uint8Array[];
|
|
74
|
+
readonly cohortEpoch: Uint8Array;
|
|
75
|
+
/** The accepted register's correlation id, base64url — echoed on every later renew. */
|
|
76
|
+
readonly correlationId: string;
|
|
77
|
+
}
|
|
78
|
+
|
|
60
79
|
/** Transport the participant drives; supplied by db-p2p (FRET dial / RouteAndMaybeAct underneath). */
|
|
61
80
|
export interface RenewalParticipantTransport {
|
|
62
81
|
/** Send a renew/re-attach to `target`; resolves with the reply, rejects on RPC failure. */
|
|
63
82
|
send(target: Uint8Array, msg: RenewV1): Promise<RenewReplyV1>;
|
|
64
|
-
/**
|
|
65
|
-
|
|
83
|
+
/**
|
|
84
|
+
* Primary + all backups failed: re-run the register walk from `d_max`. Resolves the accepted walk's
|
|
85
|
+
* assignment, or `undefined` when the walk was not accepted (a back-off or redirect it could not finish).
|
|
86
|
+
*/
|
|
87
|
+
relookup(): Promise<RenewalAssignment | undefined>;
|
|
66
88
|
}
|
|
67
89
|
|
|
68
90
|
export interface RenewalParticipantDeps {
|
|
@@ -71,7 +93,7 @@ export interface RenewalParticipantDeps {
|
|
|
71
93
|
clock: () => number;
|
|
72
94
|
/** Signs the renew body; db-p2p supplies the (async) peer-key signature. */
|
|
73
95
|
sign: (body: UnsignedRenew) => Promise<string>;
|
|
74
|
-
/** Correlation id matching the original RegisterV1, base64url. */
|
|
96
|
+
/** Correlation id matching the original RegisterV1, base64url; replaced when a relookup lands. */
|
|
75
97
|
correlationId: string;
|
|
76
98
|
/** Initial cohort-epoch hint from the registration reply (refreshed lazily thereafter). */
|
|
77
99
|
initialCohortEpoch?: Uint8Array;
|
|
@@ -81,10 +103,12 @@ class TtlRenewalParticipant implements RenewalParticipant {
|
|
|
81
103
|
private consecutiveFailures = 0;
|
|
82
104
|
private current: RegistrationRecord;
|
|
83
105
|
private epochHint: Uint8Array | undefined;
|
|
106
|
+
private correlationId: string;
|
|
84
107
|
|
|
85
108
|
constructor(initial: RegistrationRecord, private readonly deps: RenewalParticipantDeps) {
|
|
86
109
|
this.current = initial;
|
|
87
110
|
this.epochHint = deps.initialCohortEpoch;
|
|
111
|
+
this.correlationId = deps.correlationId;
|
|
88
112
|
}
|
|
89
113
|
|
|
90
114
|
get record(): RegistrationRecord {
|
|
@@ -101,15 +125,10 @@ class TtlRenewalParticipant implements RenewalParticipant {
|
|
|
101
125
|
|
|
102
126
|
async pingLoop(): Promise<void> {
|
|
103
127
|
const reply = await this.trySend(this.current.primary);
|
|
104
|
-
if (reply !== undefined) {
|
|
105
|
-
this.onPingSuccess(reply);
|
|
106
|
-
return;
|
|
107
|
-
}
|
|
108
|
-
this.consecutiveFailures++;
|
|
109
|
-
if (this.consecutiveFailures < MAX_PING_FAILURES) {
|
|
128
|
+
if (reply !== undefined && this.acceptPingReply(reply)) {
|
|
110
129
|
return;
|
|
111
130
|
}
|
|
112
|
-
await this.
|
|
131
|
+
await this.strike();
|
|
113
132
|
}
|
|
114
133
|
|
|
115
134
|
async reattach(target: Uint8Array): Promise<RenewReplyV1> {
|
|
@@ -136,11 +155,37 @@ class TtlRenewalParticipant implements RenewalParticipant {
|
|
|
136
155
|
}
|
|
137
156
|
}
|
|
138
157
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
158
|
+
/**
|
|
159
|
+
* Act on the primary's answer to a plain ping. Returns `false` when the answer says the member holds no
|
|
160
|
+
* record for this participant — a failed ping, which the caller counts as a strike.
|
|
161
|
+
*/
|
|
162
|
+
private acceptPingReply(reply: RenewReplyV1): boolean {
|
|
163
|
+
switch (reply.result) {
|
|
164
|
+
case "ok": {
|
|
165
|
+
this.consecutiveFailures = 0;
|
|
166
|
+
return true;
|
|
167
|
+
}
|
|
168
|
+
case "primary_moved": {
|
|
169
|
+
this.consecutiveFailures = 0;
|
|
170
|
+
// Lazy cohortEpoch refresh lands here: a move discovered on a normal ping updates the hint.
|
|
171
|
+
this.applyPrimaryMoved(reply);
|
|
172
|
+
return true;
|
|
173
|
+
}
|
|
174
|
+
case "unknown_registration":
|
|
175
|
+
case "withdrawn":
|
|
176
|
+
return false;
|
|
177
|
+
default: {
|
|
178
|
+
const unexpected: never = reply.result;
|
|
179
|
+
throw new Error(`cohort-topic: unexpected renew result ${String(unexpected)}`);
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/** Count a failed ping; the {@link MAX_PING_FAILURES}th in a row fails over. */
|
|
185
|
+
private async strike(): Promise<void> {
|
|
186
|
+
this.consecutiveFailures++;
|
|
187
|
+
if (this.consecutiveFailures >= MAX_PING_FAILURES) {
|
|
188
|
+
await this.failover();
|
|
144
189
|
}
|
|
145
190
|
}
|
|
146
191
|
|
|
@@ -149,7 +194,7 @@ class TtlRenewalParticipant implements RenewalParticipant {
|
|
|
149
194
|
* backup accepted the crash-failover promotion → promote it locally. A `primary_moved` means a real
|
|
150
195
|
* rotation moved primary to a different live member → adopt that payload (not the contacted backup),
|
|
151
196
|
* **unless** it points back at the just-failed primary (the bounce guard) — then keep trying. All
|
|
152
|
-
* backups exhausted → re-run lookup from `d_max
|
|
197
|
+
* backups exhausted → re-run lookup from `d_max` and adopt where it landed.
|
|
153
198
|
*/
|
|
154
199
|
private async failover(): Promise<void> {
|
|
155
200
|
const failedPrimary = this.current.primary;
|
|
@@ -177,11 +222,29 @@ class TtlRenewalParticipant implements RenewalParticipant {
|
|
|
177
222
|
}
|
|
178
223
|
// unknown_registration (replication lag) or anything else: try the next backup.
|
|
179
224
|
}
|
|
180
|
-
|
|
181
|
-
//
|
|
182
|
-
//
|
|
183
|
-
|
|
184
|
-
|
|
225
|
+
// Reset the counter however the relookup ends — landed, not accepted, or thrown — so a registration
|
|
226
|
+
// that stays unreachable backs off to one d_max walk per MAX_PING_FAILURES pings rather than one per
|
|
227
|
+
// ping. A throw still propagates to the caller of `pingLoop`.
|
|
228
|
+
try {
|
|
229
|
+
const landing = await this.deps.transport.relookup();
|
|
230
|
+
if (landing !== undefined) {
|
|
231
|
+
this.adopt(landing);
|
|
232
|
+
}
|
|
233
|
+
} finally {
|
|
234
|
+
this.consecutiveFailures = 0;
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** Take a re-walk's assignment as the registration: later pings go to its primary under its correlation id. */
|
|
239
|
+
private adopt(landing: RenewalAssignment): void {
|
|
240
|
+
this.current = {
|
|
241
|
+
...this.current,
|
|
242
|
+
primary: landing.primary,
|
|
243
|
+
backups: [...landing.backups],
|
|
244
|
+
lastPing: this.deps.clock(),
|
|
245
|
+
};
|
|
246
|
+
this.epochHint = landing.cohortEpoch;
|
|
247
|
+
this.correlationId = landing.correlationId;
|
|
185
248
|
}
|
|
186
249
|
|
|
187
250
|
private async tryReattach(target: Uint8Array): Promise<RenewReplyV1 | undefined> {
|
|
@@ -228,7 +291,7 @@ class TtlRenewalParticipant implements RenewalParticipant {
|
|
|
228
291
|
v: 1,
|
|
229
292
|
topicId: bytesKey(this.current.topicId),
|
|
230
293
|
participantId: bytesKey(this.current.participantId),
|
|
231
|
-
correlationId: this.
|
|
294
|
+
correlationId: this.correlationId,
|
|
232
295
|
timestamp: this.deps.clock(),
|
|
233
296
|
};
|
|
234
297
|
if (opts.reattach === true) {
|
|
@@ -22,9 +22,15 @@ import { randomBytes } from "@noble/hashes/utils.js";
|
|
|
22
22
|
import { createTierAddressing, type TierAddressing } from "./addressing.js";
|
|
23
23
|
import { makeDMaxComputer, type DMaxComputer } from "./dmax.js";
|
|
24
24
|
import { DEFAULT_FANOUT } from "./addressing.js";
|
|
25
|
-
import type { ISizeEstimator, ITopicRouter, IRingHash
|
|
26
|
-
import { createWalkEngine, type RegisterMessageFactory, type WalkEngine, type WalkOutcome } from "./walk.js";
|
|
27
|
-
import {
|
|
25
|
+
import type { ISizeEstimator, ITopicRouter, IRingHash } from "./ports.js";
|
|
26
|
+
import { createWalkEngine, type AcceptedWalkOutcome, type RegisterMessageFactory, type WalkEngine, type WalkOutcome } from "./walk.js";
|
|
27
|
+
import {
|
|
28
|
+
createRenewalParticipant,
|
|
29
|
+
type RenewalAssignment,
|
|
30
|
+
type RenewalParticipant,
|
|
31
|
+
type RenewalParticipantTransport,
|
|
32
|
+
type UnsignedRenew,
|
|
33
|
+
} from "./registration/renewal.js";
|
|
28
34
|
import type { RegistrationRecord } from "./registration/types.js";
|
|
29
35
|
import { DEFAULT_TTL_MS } from "./registration/types.js";
|
|
30
36
|
import { recordKey } from "./registration/bytes.js";
|
|
@@ -32,13 +38,20 @@ import type { CohortGossipBus } from "./gossip/bus.js";
|
|
|
32
38
|
import type { MembershipVerifier } from "./membership/verifier.js";
|
|
33
39
|
import type { Tier } from "./tiers.js";
|
|
34
40
|
import { bytesToB64url, b64urlToBytes, decodeRenewReplyV1, encodeCohortMessage } from "./wire/codec.js";
|
|
35
|
-
import
|
|
41
|
+
import { MAX_ROOT_KEY_BYTES } from "./wire/validate.js";
|
|
42
|
+
import type { RegisterV1, RenewReplyV1, TopicTrafficV1 } from "./wire/types.js";
|
|
36
43
|
import type { CollectionChangeEvent, CommitCert } from "../transactor/change-notifier.js";
|
|
37
44
|
|
|
38
45
|
/** A resolved cohort for a topic/tier — the return of {@link CohortTopicService.lookup}. */
|
|
39
46
|
export interface CohortHint {
|
|
40
47
|
readonly topicId: Uint8Array;
|
|
41
48
|
readonly tier: Tier;
|
|
49
|
+
/**
|
|
50
|
+
* The tree tier `d` the walk landed at: `0` is the topic's root cohort, `d ≥ 1` a cohort below it. A
|
|
51
|
+
* root-placed topic's root can move while the tiers below it stay put, so a caller following a moved
|
|
52
|
+
* root reads this to choose between {@link CohortTopicService.moveRoot} and registering again.
|
|
53
|
+
*/
|
|
54
|
+
readonly treeTier: number;
|
|
42
55
|
/** Serving cohort member. */
|
|
43
56
|
readonly primary: Uint8Array;
|
|
44
57
|
/** Warm-failover cohort members (1..2). */
|
|
@@ -48,6 +61,13 @@ export interface CohortHint {
|
|
|
48
61
|
readonly cohortMembers: Uint8Array[];
|
|
49
62
|
/** Coarse traffic barometer, when the cohort attached one. */
|
|
50
63
|
readonly topicTraffic?: TopicTrafficV1;
|
|
64
|
+
/**
|
|
65
|
+
* The root key the topic was resolved under, when it is root-placed (its tier-0 cohort sits at
|
|
66
|
+
* `H(rootKey)`) — on a handle, the key {@link CohortTopicService.moveRoot} last named, which a handle at
|
|
67
|
+
* the root (`treeTier` 0) holds before it has registered there. Absent for the default addressing. A
|
|
68
|
+
* caller verifying a message signed by that root needs it to know the root's threshold rule applies.
|
|
69
|
+
*/
|
|
70
|
+
readonly rootKey?: Uint8Array;
|
|
51
71
|
}
|
|
52
72
|
|
|
53
73
|
/** A live registration: a {@link CohortHint} plus the participant-side renewal handle behind it. */
|
|
@@ -85,6 +105,13 @@ export interface RegisterRequest {
|
|
|
85
105
|
readonly ttl?: number;
|
|
86
106
|
/** Mark this a cold-root bootstrap request. */
|
|
87
107
|
readonly bootstrap?: boolean;
|
|
108
|
+
/**
|
|
109
|
+
* Place this topic's root at a routing key: raw key bytes (1..`MAX_ROOT_KEY_BYTES`), e.g. a block's
|
|
110
|
+
* routing key. The topic's tier-0 cohort is then the group responsible for that key, at `H(rootKey)`,
|
|
111
|
+
* instead of the cohort at `H(0x00 ‖ topicId)` (§Tier addressing → Root placement at a routing key).
|
|
112
|
+
* Every participant of one topic must name the same key. Absent → the default addressing.
|
|
113
|
+
*/
|
|
114
|
+
readonly rootKey?: Uint8Array;
|
|
88
115
|
}
|
|
89
116
|
|
|
90
117
|
/** The substrate's participant-facing contract. */
|
|
@@ -93,11 +120,23 @@ export interface CohortTopicService {
|
|
|
93
120
|
register(req: RegisterRequest): Promise<RegistrationHandle>;
|
|
94
121
|
/** Run one `ttl/3` renewal cycle for `handle` (handles `primary_moved` + crash-failover). */
|
|
95
122
|
renew(handle: RegistrationHandle): Promise<void>;
|
|
96
|
-
/**
|
|
97
|
-
|
|
123
|
+
/**
|
|
124
|
+
* Resolve the cohort for `topicId` at `tier` without keeping a live registration. `rootKey` names the
|
|
125
|
+
* root of a root-placed topic (see {@link RegisterRequest.rootKey}).
|
|
126
|
+
*/
|
|
127
|
+
lookup(topicId: Uint8Array, tier: Tier, rootKey?: Uint8Array): Promise<CohortHint>;
|
|
98
128
|
/** Stop renewing `handle` and send a best-effort signed withdraw tombstone so the cohort frees the
|
|
99
129
|
* record immediately (TTL expiry remains the fallback if the primary is unreachable). */
|
|
100
130
|
withdraw(handle: RegistrationHandle): Promise<void>;
|
|
131
|
+
/**
|
|
132
|
+
* The topic's root moved to `rootKey` (a root-placed topic only — a handle registered without a root key
|
|
133
|
+
* throws). Nothing is sent: a registration at a tier below the root stays where it is. A later re-walk of
|
|
134
|
+
* this registration (renewal failover) names the new key, so it lands at the new root rather than the old
|
|
135
|
+
* one. A registration AT the root (`handle.treeTier === 0`) is left at the old root by this call and must
|
|
136
|
+
* be re-registered instead — `register` with the new key displaces it (see the NOTE at `startRenewal`).
|
|
137
|
+
* A stale handle (no longer the live registration for its topic) is a no-op.
|
|
138
|
+
*/
|
|
139
|
+
moveRoot(handle: RegistrationHandle, rootKey: Uint8Array): void;
|
|
101
140
|
/** Origination hook the change-notifier bridge invokes per local member commit; see {@link LocalChangeHook}. */
|
|
102
141
|
onLocalCommit?: LocalChangeHook;
|
|
103
142
|
/** Cohort gossip bus — applications fold app state into the existing gossip. */
|
|
@@ -175,6 +214,29 @@ export interface CohortTopicServiceDeps {
|
|
|
175
214
|
readonly config?: CohortServiceConfig;
|
|
176
215
|
}
|
|
177
216
|
|
|
217
|
+
/** The root key a renewal's re-walk names — mutable, so {@link CohortTopicService.moveRoot} can re-point it. */
|
|
218
|
+
interface RootKeySlot {
|
|
219
|
+
key: Uint8Array | undefined;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* What the walk that last placed a registration reported beyond its primary, backups and epoch — set by the
|
|
224
|
+
* register, replaced by each renewal re-walk. The participant's record stays the authority for primary,
|
|
225
|
+
* backups and epoch, since later `primary_moved` replies change those without a walk.
|
|
226
|
+
*/
|
|
227
|
+
interface WalkLanding {
|
|
228
|
+
treeTier: number;
|
|
229
|
+
cohortMembers: Uint8Array[];
|
|
230
|
+
topicTraffic: TopicTrafficV1 | undefined;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** A live registration's renewal driver, the root key its re-walk reads, and where it last landed. */
|
|
234
|
+
interface LiveRenewal {
|
|
235
|
+
readonly renewal: RenewalParticipant;
|
|
236
|
+
readonly root: RootKeySlot;
|
|
237
|
+
readonly landing: WalkLanding;
|
|
238
|
+
}
|
|
239
|
+
|
|
178
240
|
class WalkRegisterService implements CohortTopicService {
|
|
179
241
|
public onLocalCommit?: LocalChangeHook;
|
|
180
242
|
|
|
@@ -184,8 +246,8 @@ class WalkRegisterService implements CohortTopicService {
|
|
|
184
246
|
private readonly clock: () => number;
|
|
185
247
|
private readonly ttl: number;
|
|
186
248
|
private readonly maxMessageBytes?: number;
|
|
187
|
-
/** Live
|
|
188
|
-
private readonly renewals = new Map<string,
|
|
249
|
+
/** Live renewals, keyed by `(topicId, participantId)` so renew/withdraw/moveRoot find their handle. */
|
|
250
|
+
private readonly renewals = new Map<string, LiveRenewal>();
|
|
189
251
|
private readonly participantId: Uint8Array;
|
|
190
252
|
|
|
191
253
|
constructor(private readonly deps: CohortTopicServiceDeps) {
|
|
@@ -213,32 +275,48 @@ class WalkRegisterService implements CohortTopicService {
|
|
|
213
275
|
}
|
|
214
276
|
|
|
215
277
|
async register(req: RegisterRequest): Promise<RegistrationHandle> {
|
|
216
|
-
|
|
278
|
+
assertRootKey(req.rootKey);
|
|
279
|
+
const outcome = await this.walk.register(req.topicId, req.tier, req.appPayload, { rootKey: req.rootKey });
|
|
217
280
|
return this.handleFromOutcome(req, outcome);
|
|
218
281
|
}
|
|
219
282
|
|
|
220
|
-
async lookup(topicId: Uint8Array, tier: Tier): Promise<CohortHint> {
|
|
283
|
+
async lookup(topicId: Uint8Array, tier: Tier, rootKey?: Uint8Array): Promise<CohortHint> {
|
|
284
|
+
assertRootKey(rootKey);
|
|
221
285
|
// A read-only probe: it walks to the responsible cohort exactly as a register would and returns the
|
|
222
286
|
// same cohort snapshot, but admits NOTHING — no soft-state record, no arrival, no promotion trigger,
|
|
223
287
|
// no topic-budget touch, and never a cold-start instantiation. A topic served nowhere resolves to a
|
|
224
288
|
// `CohortBackoffError` (the probe never bootstraps a cold root), so a lookup leaves no throwaway
|
|
225
289
|
// registration behind to TTL-expire (§Application policies; the lookup-as-register interim is gone).
|
|
226
|
-
const outcome = await this.walk.register(topicId, tier, undefined, { probe: true });
|
|
290
|
+
const outcome = await this.walk.register(topicId, tier, undefined, { probe: true, rootKey });
|
|
227
291
|
if (outcome.kind !== "accepted") {
|
|
228
292
|
throw new CohortBackoffError(outcome.kind === "retry_later" ? outcome.afterMs : 0);
|
|
229
293
|
}
|
|
230
|
-
return this.hintFromReply(topicId, tier, outcome
|
|
294
|
+
return this.hintFromReply(topicId, tier, outcome, rootKey);
|
|
231
295
|
}
|
|
232
296
|
|
|
233
297
|
async renew(handle: RegistrationHandle): Promise<void> {
|
|
234
298
|
// Act only if this handle is still the live entry. A stale handle (superseded by a second
|
|
235
299
|
// register() for the same pair) must not drive the new registration's ping loop, and a
|
|
236
300
|
// withdrawn handle must not silently re-start it.
|
|
237
|
-
|
|
301
|
+
const live = this.liveRenewal(handle);
|
|
302
|
+
if (live === undefined) {
|
|
238
303
|
return;
|
|
239
304
|
}
|
|
240
305
|
await handle.renewal.pingLoop();
|
|
241
|
-
this.syncHandle(handle);
|
|
306
|
+
this.syncHandle(handle, live.landing);
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
moveRoot(handle: RegistrationHandle, rootKey: Uint8Array): void {
|
|
310
|
+
assertRootKey(rootKey);
|
|
311
|
+
if (handle.rootKey === undefined) {
|
|
312
|
+
throw new Error("cohort-topic: moveRoot needs a root-placed registration; this one was registered without a rootKey");
|
|
313
|
+
}
|
|
314
|
+
const live = this.liveRenewal(handle);
|
|
315
|
+
if (live === undefined) {
|
|
316
|
+
return;
|
|
317
|
+
}
|
|
318
|
+
live.root.key = rootKey;
|
|
319
|
+
(handle as { rootKey?: Uint8Array }).rootKey = rootKey;
|
|
242
320
|
}
|
|
243
321
|
|
|
244
322
|
async withdraw(handle: RegistrationHandle): Promise<void> {
|
|
@@ -247,17 +325,16 @@ class WalkRegisterService implements CohortTopicService {
|
|
|
247
325
|
// primary so the cohort frees the record immediately instead of holding it for up to a full TTL.
|
|
248
326
|
// The delete happens FIRST so a concurrent renew() already no-ops before the tombstone is sent. If
|
|
249
327
|
// the tombstone send fails (primary unreachable), the cohort soft-state TTL-expires as the
|
|
250
|
-
// fallback — withdraw never throws on a transport failure. Idempotent: a second withdraw finds
|
|
251
|
-
//
|
|
328
|
+
// fallback — withdraw never throws on a transport failure. Idempotent: a second withdraw finds no
|
|
329
|
+
// live entry for the handle and no-ops.
|
|
252
330
|
// Guard: act only if this handle is still the live entry. A stale handle must not evict the
|
|
253
331
|
// new registration or send a tombstone on its behalf.
|
|
254
|
-
const
|
|
255
|
-
|
|
256
|
-
if (renewal !== handle.renewal) {
|
|
332
|
+
const live = this.liveRenewal(handle);
|
|
333
|
+
if (live === undefined) {
|
|
257
334
|
return;
|
|
258
335
|
}
|
|
259
|
-
this.renewals.delete(
|
|
260
|
-
await renewal.withdraw();
|
|
336
|
+
this.renewals.delete(recordKey(handle.topicId, this.participantId));
|
|
337
|
+
await live.renewal.withdraw();
|
|
261
338
|
}
|
|
262
339
|
|
|
263
340
|
cohortGossip(): CohortGossipBus {
|
|
@@ -274,11 +351,17 @@ class WalkRegisterService implements CohortTopicService {
|
|
|
274
351
|
if (outcome.kind !== "accepted") {
|
|
275
352
|
throw new CohortBackoffError(outcome.kind === "retry_later" ? outcome.afterMs : 0);
|
|
276
353
|
}
|
|
277
|
-
const hint = this.hintFromReply(req.topicId, req.tier, outcome.
|
|
354
|
+
const hint = this.hintFromReply(req.topicId, req.tier, outcome, req.rootKey);
|
|
278
355
|
const renewal = this.startRenewal(req, hint, outcome.correlationId);
|
|
279
356
|
return { ...hint, renewal };
|
|
280
357
|
}
|
|
281
358
|
|
|
359
|
+
/** The live renewal `handle` drives, or `undefined` when a later register displaced it or it was withdrawn. */
|
|
360
|
+
private liveRenewal(handle: RegistrationHandle): LiveRenewal | undefined {
|
|
361
|
+
const live = this.renewals.get(recordKey(handle.topicId, this.participantId));
|
|
362
|
+
return live?.renewal === handle.renewal ? live : undefined;
|
|
363
|
+
}
|
|
364
|
+
|
|
282
365
|
private startRenewal(req: RegisterRequest, hint: CohortHint, correlationId: string): RenewalParticipant {
|
|
283
366
|
const ttl = req.ttl ?? this.ttl;
|
|
284
367
|
const initial: RegistrationRecord = {
|
|
@@ -292,7 +375,9 @@ class WalkRegisterService implements CohortTopicService {
|
|
|
292
375
|
ttl,
|
|
293
376
|
appState: req.appPayload,
|
|
294
377
|
};
|
|
295
|
-
const
|
|
378
|
+
const root: RootKeySlot = { key: req.rootKey };
|
|
379
|
+
const landing: WalkLanding = { treeTier: hint.treeTier, cohortMembers: hint.cohortMembers, topicTraffic: hint.topicTraffic };
|
|
380
|
+
const transport = this.renewalTransport(req, root, landing);
|
|
296
381
|
const renewal = createRenewalParticipant(initial, {
|
|
297
382
|
transport,
|
|
298
383
|
clock: this.clock,
|
|
@@ -307,44 +392,65 @@ class WalkRegisterService implements CohortTopicService {
|
|
|
307
392
|
correlationId,
|
|
308
393
|
initialCohortEpoch: hint.cohortEpoch,
|
|
309
394
|
});
|
|
310
|
-
// NOTE: a second register() for the same (topicId, participantId)
|
|
311
|
-
//
|
|
312
|
-
//
|
|
313
|
-
//
|
|
314
|
-
//
|
|
315
|
-
|
|
395
|
+
// NOTE: accepted — a second register() for the same (topicId, participantId) displaces the first:
|
|
396
|
+
// renew()/withdraw()/moveRoot() on the displaced handle no-op (identity guard), and NO tombstone is
|
|
397
|
+
// sent for the displaced record, by design. A participant re-registers at a moved root while its old
|
|
398
|
+
// record still lives at the old one, and a machine in both roots' storage groups holds both; a
|
|
399
|
+
// tombstone resolves through the host's `findHolder`, which picks the newer record there, so it would
|
|
400
|
+
// evict the live registration. The displaced record expires by TTL at its cohort.
|
|
401
|
+
this.renewals.set(recordKey(req.topicId, this.participantId), { renewal, root, landing });
|
|
316
402
|
return renewal;
|
|
317
403
|
}
|
|
318
404
|
|
|
319
|
-
/**
|
|
320
|
-
|
|
405
|
+
/**
|
|
406
|
+
* Renewal transport: dial the cached primary directly; a full failure re-runs the register walk. The
|
|
407
|
+
* re-walk reads the root key from `root` when it runs, so after {@link CohortTopicService.moveRoot} it
|
|
408
|
+
* lands at the topic's current root rather than the one it registered under. An accepted re-walk records
|
|
409
|
+
* its tree tier, cohort and traffic in `landing` and hands its assignment to the participant to adopt.
|
|
410
|
+
*/
|
|
411
|
+
private renewalTransport(req: RegisterRequest, root: RootKeySlot, landing: WalkLanding): RenewalParticipantTransport {
|
|
321
412
|
return {
|
|
322
413
|
send: async (target: Uint8Array, msg): Promise<RenewReplyV1> => {
|
|
323
414
|
const raw = await this.deps.router.dialMember({ id: target }, encodeCohortMessage(msg, this.maxMessageBytes));
|
|
324
415
|
return decodeRenewReplyV1(raw, this.maxMessageBytes);
|
|
325
416
|
},
|
|
326
|
-
relookup: async (): Promise<
|
|
327
|
-
|
|
417
|
+
relookup: async (): Promise<RenewalAssignment | undefined> => {
|
|
418
|
+
// NOTE: re-sends the first registration's `appPayload` (for a collection watch, its `tailIdAtAttach`
|
|
419
|
+
// and `lastKnownRev`). No cohort reads those fields off a held record today; if one ever does, the
|
|
420
|
+
// re-walk needs a fresh payload from the registering caller.
|
|
421
|
+
const outcome = await this.walk.register(req.topicId, req.tier, req.appPayload, { rootKey: root.key });
|
|
422
|
+
if (outcome.kind !== "accepted") {
|
|
423
|
+
return undefined;
|
|
424
|
+
}
|
|
425
|
+
const hint = this.hintFromReply(req.topicId, req.tier, outcome, root.key);
|
|
426
|
+
landing.treeTier = hint.treeTier;
|
|
427
|
+
landing.cohortMembers = hint.cohortMembers;
|
|
428
|
+
landing.topicTraffic = hint.topicTraffic;
|
|
429
|
+
return { primary: hint.primary, backups: hint.backups, cohortEpoch: hint.cohortEpoch, correlationId: outcome.correlationId };
|
|
328
430
|
},
|
|
329
431
|
};
|
|
330
432
|
}
|
|
331
433
|
|
|
332
|
-
private hintFromReply(topicId: Uint8Array, tier: Tier,
|
|
434
|
+
private hintFromReply(topicId: Uint8Array, tier: Tier, outcome: AcceptedWalkOutcome, rootKey: Uint8Array | undefined): CohortHint {
|
|
435
|
+
const reply = outcome.reply;
|
|
333
436
|
if (reply.primary === undefined || reply.cohortEpoch === undefined) {
|
|
334
437
|
throw new CohortBackoffError(0);
|
|
335
438
|
}
|
|
336
439
|
return {
|
|
337
440
|
topicId,
|
|
338
441
|
tier,
|
|
442
|
+
treeTier: outcome.treeTier,
|
|
339
443
|
primary: b64urlToBytes(reply.primary),
|
|
340
444
|
backups: (reply.backups ?? []).map(b64urlToBytes),
|
|
341
445
|
cohortEpoch: b64urlToBytes(reply.cohortEpoch),
|
|
342
446
|
cohortMembers: (reply.cohortMembers ?? []).map(b64urlToBytes),
|
|
343
447
|
topicTraffic: reply.topicTraffic,
|
|
448
|
+
...(rootKey === undefined ? {} : { rootKey }),
|
|
344
449
|
};
|
|
345
450
|
}
|
|
346
451
|
|
|
347
|
-
|
|
452
|
+
/** Copy the registration's current placement onto `handle`: the participant's record, and the last walk's landing. */
|
|
453
|
+
private syncHandle(handle: RegistrationHandle, landing: WalkLanding): void {
|
|
348
454
|
const rec = handle.renewal.record;
|
|
349
455
|
(handle as { primary: Uint8Array }).primary = rec.primary;
|
|
350
456
|
(handle as { backups: Uint8Array[] }).backups = [...rec.backups];
|
|
@@ -352,6 +458,9 @@ class WalkRegisterService implements CohortTopicService {
|
|
|
352
458
|
if (epoch !== undefined) {
|
|
353
459
|
(handle as { cohortEpoch: Uint8Array }).cohortEpoch = epoch;
|
|
354
460
|
}
|
|
461
|
+
(handle as { treeTier: number }).treeTier = landing.treeTier;
|
|
462
|
+
(handle as { cohortMembers: Uint8Array[] }).cohortMembers = landing.cohortMembers;
|
|
463
|
+
(handle as { topicTraffic?: TopicTrafficV1 }).topicTraffic = landing.topicTraffic;
|
|
355
464
|
}
|
|
356
465
|
|
|
357
466
|
/** The per-probe `RegisterV1` builder: stamps participant coord/ttl/correlation and signs. */
|
|
@@ -398,6 +507,9 @@ class WalkRegisterService implements CohortTopicService {
|
|
|
398
507
|
if (params.appPayload !== undefined) {
|
|
399
508
|
body.appPayload = bytesToB64url(params.appPayload);
|
|
400
509
|
}
|
|
510
|
+
if (params.rootKey !== undefined) {
|
|
511
|
+
body.rootKey = bytesToB64url(params.rootKey);
|
|
512
|
+
}
|
|
401
513
|
return { ...body, signature: await this.deps.signer.signRegister(body) };
|
|
402
514
|
},
|
|
403
515
|
};
|
|
@@ -410,6 +522,16 @@ class WalkRegisterService implements CohortTopicService {
|
|
|
410
522
|
}
|
|
411
523
|
}
|
|
412
524
|
|
|
525
|
+
/**
|
|
526
|
+
* Reject a root key no cohort would accept. The wire validator refuses an empty or over-long `rootKey`,
|
|
527
|
+
* so sending one would only surface as a remote decode failure; it is a caller error, raised here.
|
|
528
|
+
*/
|
|
529
|
+
function assertRootKey(rootKey: Uint8Array | undefined): void {
|
|
530
|
+
if (rootKey !== undefined && (rootKey.length === 0 || rootKey.length > MAX_ROOT_KEY_BYTES)) {
|
|
531
|
+
throw new RangeError(`cohort-topic: rootKey must be 1..${MAX_ROOT_KEY_BYTES} bytes, got ${rootKey.length}`);
|
|
532
|
+
}
|
|
533
|
+
}
|
|
534
|
+
|
|
413
535
|
/** Build the participant-facing {@link CohortTopicService} over the injected ports. */
|
|
414
536
|
export function createCohortTopicService(deps: CohortTopicServiceDeps): CohortTopicService {
|
|
415
537
|
return new WalkRegisterService(deps);
|
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
* version to negotiate).
|
|
19
19
|
*/
|
|
20
20
|
|
|
21
|
+
import { presentOnly } from "../wire/payloads.js";
|
|
21
22
|
import type { ChildLinkV1, DemotionNoticeV1, MembershipCertV1, PromotionNoticeV1 } from "../wire/types.js";
|
|
22
23
|
|
|
23
24
|
const utf8 = new TextEncoder();
|
|
@@ -47,13 +48,17 @@ export function demotionNoticeSigningPayload(n: DemotionSignable): Uint8Array {
|
|
|
47
48
|
}
|
|
48
49
|
|
|
49
50
|
/** Fields of a `ChildLinkV1` covered by the child cohort's threshold signature. */
|
|
50
|
-
export type ChildLinkSignable = Pick<ChildLinkV1, "topicId" | "childCohortCoord" | "childParticipantCoord" | "childTier" | "tier" | "effectiveAt" | "cohortEpoch">;
|
|
51
|
+
export type ChildLinkSignable = Pick<ChildLinkV1, "topicId" | "childCohortCoord" | "childParticipantCoord" | "childTier" | "tier" | "effectiveAt" | "cohortEpoch" | "rootKey">;
|
|
51
52
|
|
|
52
53
|
/**
|
|
53
54
|
* Canonical signed byte image of a child-link frame. `cohortEpoch` stays **last** so the `/sign` endorser
|
|
54
55
|
* (`handleSignRequest`) reads the embedded epoch positionally as `image[image.length - 1]`, exactly as it
|
|
55
56
|
* does for a promotion / demotion notice.
|
|
57
|
+
*
|
|
58
|
+
* `rootKey` (a tier-1 child of a root-placed topic) is covered only when present, and is inserted **before**
|
|
59
|
+
* `cohortEpoch` for that same reason. A link without one keeps the eight-element image unchanged; one
|
|
60
|
+
* with it signs nine elements, so stripping or swapping the key fails verification.
|
|
56
61
|
*/
|
|
57
62
|
export function childLinkSigningPayload(n: ChildLinkSignable): Uint8Array {
|
|
58
|
-
return utf8.encode(JSON.stringify(["ChildLinkV1", n.topicId, n.childCohortCoord, n.childParticipantCoord, n.childTier, n.tier, n.effectiveAt, n.cohortEpoch]));
|
|
63
|
+
return utf8.encode(JSON.stringify(["ChildLinkV1", n.topicId, n.childCohortCoord, n.childParticipantCoord, n.childTier, n.tier, n.effectiveAt, ...presentOnly(n.rootKey), n.cohortEpoch]));
|
|
59
64
|
}
|
|
@@ -12,13 +12,42 @@
|
|
|
12
12
|
* the signature must verify against the payload. Either failure → not verified.
|
|
13
13
|
*/
|
|
14
14
|
|
|
15
|
-
import type { ICohortThresholdCrypto } from "../ports.js";
|
|
15
|
+
import type { ICohortThresholdCrypto, RootPlacement } from "../ports.js";
|
|
16
16
|
import { bytesToB64url } from "../wire/codec.js";
|
|
17
17
|
import type { MembershipCertV1 } from "../wire/types.js";
|
|
18
18
|
|
|
19
|
-
/** Default cohort-signature threshold, `k − x` (see §Configuration). */
|
|
19
|
+
/** Default cohort-signature threshold, `k − x` (see §Configuration). The rule for every coord that is not root-placed. */
|
|
20
20
|
export const DEFAULT_MIN_SIGS = 14;
|
|
21
21
|
|
|
22
|
+
/**
|
|
23
|
+
* Build the {@link RootPlacement} for a root-placed cohort from this node's own quorum ratio. A ratio
|
|
24
|
+
* outside `(0, 1]` (or not a number) is a configuration error and throws here, at construction, so
|
|
25
|
+
* verification never has to judge a malformed rule. `rootKey` is the routing key the root coordinate is
|
|
26
|
+
* the hash of, when the caller knows it (see {@link RootPlacement.rootKey}); it is carried, never checked
|
|
27
|
+
* here — the anchor that uses it checks that it hashes to the coordinate being judged.
|
|
28
|
+
*/
|
|
29
|
+
export function createRootPlacement(quorumRatio: number, rootKey?: Uint8Array): RootPlacement {
|
|
30
|
+
if (!(quorumRatio > 0 && quorumRatio <= 1)) {
|
|
31
|
+
throw new RangeError(`root placement quorumRatio must be in (0, 1], got ${quorumRatio}`);
|
|
32
|
+
}
|
|
33
|
+
return rootKey === undefined ? { quorumRatio } : { quorumRatio, rootKey };
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Signature threshold of a root-placed cohort of `memberCount` members: `ceil(memberCount × quorumRatio)`.
|
|
38
|
+
*
|
|
39
|
+
* This is the formula `captureCommitCert` (`packages/db-p2p/src/cluster/cluster-repo.ts`) applies to a
|
|
40
|
+
* storage group's commit certificate — `ceil(|group| × superMajorityThreshold)` — written the same way on
|
|
41
|
+
* purpose (same multiplication, same rounding), so a commit certificate and a verifier given the same ratio
|
|
42
|
+
* agree on the threshold by construction. One member needs 1; four members at `0.75` need 3.
|
|
43
|
+
*
|
|
44
|
+
* The floor of 1 only matters for an empty member list, where the formula would yield 0 and "no signers"
|
|
45
|
+
* would count as a quorum; with it, a cert naming no members can never verify.
|
|
46
|
+
*/
|
|
47
|
+
export function rootPlacedMinSigs(memberCount: number, placement: RootPlacement): number {
|
|
48
|
+
return Math.max(1, Math.ceil(memberCount * placement.quorumRatio));
|
|
49
|
+
}
|
|
50
|
+
|
|
22
51
|
/** Threshold signer/verifier over the injected cohort crypto. Peer ids are raw bytes. */
|
|
23
52
|
export interface CohortSigner {
|
|
24
53
|
/** Assemble a cohort threshold signature over `payload` (collects `minSigs` signers). */
|
|
@@ -31,10 +60,10 @@ export interface CohortSigner {
|
|
|
31
60
|
}
|
|
32
61
|
|
|
33
62
|
class CryptoCohortSigner implements CohortSigner {
|
|
34
|
-
constructor(private readonly crypto: ICohortThresholdCrypto, private readonly
|
|
63
|
+
constructor(private readonly crypto: ICohortThresholdCrypto, private readonly minSigsNow: () => number) {}
|
|
35
64
|
|
|
36
65
|
thresholdSign(payload: Uint8Array): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }> {
|
|
37
|
-
return this.crypto.assemble(payload, this.
|
|
66
|
+
return this.crypto.assemble(payload, this.minSigsNow());
|
|
38
67
|
}
|
|
39
68
|
|
|
40
69
|
verifyThreshold(payload: Uint8Array, sig: Uint8Array, signers: readonly Uint8Array[], cert: MembershipCertV1, minSigs: number): boolean {
|
|
@@ -58,7 +87,12 @@ class CryptoCohortSigner implements CohortSigner {
|
|
|
58
87
|
}
|
|
59
88
|
}
|
|
60
89
|
|
|
61
|
-
/**
|
|
62
|
-
|
|
63
|
-
|
|
90
|
+
/**
|
|
91
|
+
* Build a {@link CohortSigner} over the FRET-backed (in db-p2p) threshold crypto. `minSigs` is the assembly
|
|
92
|
+
* threshold: a number for a cohort whose threshold is fixed (the node-wide `k − x`), or a function read at
|
|
93
|
+
* each signing for one whose threshold follows its member count (a root-placed cohort under
|
|
94
|
+
* {@link rootPlacedMinSigs}). Verification takes its threshold as an argument either way.
|
|
95
|
+
*/
|
|
96
|
+
export function createCohortSigner(crypto: ICohortThresholdCrypto, minSigs: number | (() => number) = DEFAULT_MIN_SIGS): CohortSigner {
|
|
97
|
+
return new CryptoCohortSigner(crypto, typeof minSigs === "number" ? (): number => minSigs : minSigs);
|
|
64
98
|
}
|