@optimystic/db-core 1.9.0 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/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/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/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
|
@@ -1,46 +1,51 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Reactivity —
|
|
2
|
+
* Reactivity — the collection anchor: one topic per collection, a root that follows the tail.
|
|
3
3
|
*
|
|
4
4
|
* Transcribed from `docs/reactivity.md` §Anchor:
|
|
5
5
|
*
|
|
6
6
|
* ```
|
|
7
|
-
* topicId(
|
|
7
|
+
* topicId(C) = H(utf8(C.collectionId) ‖ "reactivity") (stable for the collection's life)
|
|
8
|
+
* coord_0 = H(tailId) (the root: the tail block's storage group; moves on rotation)
|
|
9
|
+
* coord_d(P) = H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) (d ≥ 1; never moves)
|
|
8
10
|
* ```
|
|
9
11
|
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
* the
|
|
13
|
-
* the
|
|
12
|
+
* Like matchmaking's `(kind, label)` anchor, the reactivity topic is **stable**: it is a function of the
|
|
13
|
+
* collection id alone, so the tiers below the root sit at fixed positions for the collection's life. What
|
|
14
|
+
* moves is the **root**. The root (announcing) group is the tail block's own storage group — the machines
|
|
15
|
+
* that apply, and so announce, the collection's commits — at `H(tailId)`, the ring position the key network
|
|
16
|
+
* places the tail by. When the tail block fills and a new one is born, the root moves to the new tail's
|
|
17
|
+
* storage group and nothing else does: a rotation is "same topic, the root moved"
|
|
18
|
+
* (`docs/reactivity.md` §Tail rotation).
|
|
14
19
|
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
20
|
+
* Both derivations use the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
|
|
21
|
+
* db-core's own SHA-256 truncated to the ring width, **not** a FRET import — because the topic id is fed
|
|
22
|
+
* verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`) and the root coordinate must equal the
|
|
23
|
+
* key network's placement of the tail block byte for byte. The trailing `"reactivity"` literal domain-separates
|
|
24
|
+
* the topic from any other application anchoring on the same collection id, and from the root coordinate,
|
|
25
|
+
* which hashes the bare tail bytes. Concatenation is delimiter-free, exactly as the spec writes it; the
|
|
26
|
+
* constant suffix is unambiguous because no collection-id byte string can alias a `(collectionId, "reactivity")`
|
|
27
|
+
* pair of a different length.
|
|
19
28
|
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
* ([reactivity-rotation-backpressure-policy]) reuses per-emission — define it here, not at the call site.
|
|
29
|
+
* `collectionId` is the UTF-8 of the id exactly as blocks carry it (`header.collectionId`, e.g. `app/users`) —
|
|
30
|
+
* the same bytes a notification's `collectionId` encodes (`reactivityCollectionIdBytes` in db-p2p's
|
|
31
|
+
* `reactivity/topic-bytes.ts`). Origination and every subscriber derive the topic from those bytes, so a
|
|
32
|
+
* notification routes to exactly the managers watching its collection.
|
|
25
33
|
*/
|
|
26
|
-
import type { IRingHash } from "../cohort-topic/ports.js";
|
|
34
|
+
import type { IRingHash, RingCoord } from "../cohort-topic/ports.js";
|
|
27
35
|
/**
|
|
28
|
-
* `H(
|
|
29
|
-
* reactivity tree
|
|
30
|
-
*
|
|
31
|
-
* The shared helper consumed by subscriber attachment, origination, and (per-emission) the rotation
|
|
32
|
-
* ticket. `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
|
|
36
|
+
* `H(collectionId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` of a collection's
|
|
37
|
+
* reactivity tree, stable for the collection's life. `collectionId` is the UTF-8 of the id as blocks carry it.
|
|
38
|
+
* `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
|
|
33
39
|
*/
|
|
34
|
-
export declare function
|
|
35
|
-
/** Derives the rotating `topicId` for a collection's current tail. */
|
|
36
|
-
export interface ReactivityTopicAnchor {
|
|
37
|
-
/** `H(tailId ‖ "reactivity")` for the given tail block id (bytes). */
|
|
38
|
-
topicId(tailId: Uint8Array): Uint8Array;
|
|
39
|
-
}
|
|
40
|
+
export declare function reactivityCollectionTopicId(collectionId: Uint8Array, hash?: IRingHash): Uint8Array;
|
|
40
41
|
/**
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
42
|
+
* The reactivity root coordinate for a tail: `H(tailId)` over the injected ring hash — the tail block's
|
|
43
|
+
* own ring position, where its storage group sits. `tailId` is the tail's routing key bytes (the raw utf8
|
|
44
|
+
* of the block id, `reactivityTailBytes` on a node), so at the default 256-bit ring width this equals the
|
|
45
|
+
* key network's `hashKey(routingKeyForBlock(tail))` byte for byte; the `topic-bytes-encoding` spec in
|
|
46
|
+
* db-p2p pins that equality. Every party that derives the root group — the notification verifier, the
|
|
47
|
+
* subscriber walk's root step, the forwarder's gossip and recover reads — must start from this one value.
|
|
48
|
+
* It is the one coordinate of a collection's tree that changes when the tail rotates.
|
|
44
49
|
*/
|
|
45
|
-
export declare function
|
|
50
|
+
export declare function reactivityRootCoord(tailId: Uint8Array, hash?: IRingHash): RingCoord;
|
|
46
51
|
//# sourceMappingURL=topic-anchor.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"topic-anchor.d.ts","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"topic-anchor.d.ts","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAOrE;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,UAAU,EAAE,IAAI,GAAE,SAA4B,GAAG,UAAU,CAMpH;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,SAA4B,GAAG,SAAS,CAErG"}
|
|
@@ -1,61 +1,63 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Reactivity —
|
|
2
|
+
* Reactivity — the collection anchor: one topic per collection, a root that follows the tail.
|
|
3
3
|
*
|
|
4
4
|
* Transcribed from `docs/reactivity.md` §Anchor:
|
|
5
5
|
*
|
|
6
6
|
* ```
|
|
7
|
-
* topicId(
|
|
7
|
+
* topicId(C) = H(utf8(C.collectionId) ‖ "reactivity") (stable for the collection's life)
|
|
8
|
+
* coord_0 = H(tailId) (the root: the tail block's storage group; moves on rotation)
|
|
9
|
+
* coord_d(P) = H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) (d ≥ 1; never moves)
|
|
8
10
|
* ```
|
|
9
11
|
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
* the
|
|
13
|
-
* the
|
|
12
|
+
* Like matchmaking's `(kind, label)` anchor, the reactivity topic is **stable**: it is a function of the
|
|
13
|
+
* collection id alone, so the tiers below the root sit at fixed positions for the collection's life. What
|
|
14
|
+
* moves is the **root**. The root (announcing) group is the tail block's own storage group — the machines
|
|
15
|
+
* that apply, and so announce, the collection's commits — at `H(tailId)`, the ring position the key network
|
|
16
|
+
* places the tail by. When the tail block fills and a new one is born, the root moves to the new tail's
|
|
17
|
+
* storage group and nothing else does: a rotation is "same topic, the root moved"
|
|
18
|
+
* (`docs/reactivity.md` §Tail rotation).
|
|
14
19
|
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
20
|
+
* Both derivations use the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
|
|
21
|
+
* db-core's own SHA-256 truncated to the ring width, **not** a FRET import — because the topic id is fed
|
|
22
|
+
* verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`) and the root coordinate must equal the
|
|
23
|
+
* key network's placement of the tail block byte for byte. The trailing `"reactivity"` literal domain-separates
|
|
24
|
+
* the topic from any other application anchoring on the same collection id, and from the root coordinate,
|
|
25
|
+
* which hashes the bare tail bytes. Concatenation is delimiter-free, exactly as the spec writes it; the
|
|
26
|
+
* constant suffix is unambiguous because no collection-id byte string can alias a `(collectionId, "reactivity")`
|
|
27
|
+
* pair of a different length.
|
|
19
28
|
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
* ([reactivity-rotation-backpressure-policy]) reuses per-emission — define it here, not at the call site.
|
|
29
|
+
* `collectionId` is the UTF-8 of the id exactly as blocks carry it (`header.collectionId`, e.g. `app/users`) —
|
|
30
|
+
* the same bytes a notification's `collectionId` encodes (`reactivityCollectionIdBytes` in db-p2p's
|
|
31
|
+
* `reactivity/topic-bytes.ts`). Origination and every subscriber derive the topic from those bytes, so a
|
|
32
|
+
* notification routes to exactly the managers watching its collection.
|
|
25
33
|
*/
|
|
26
34
|
import { createRingHash } from "../cohort-topic/ring-hash.js";
|
|
27
|
-
|
|
35
|
+
import { createTierAddressing } from "../cohort-topic/addressing.js";
|
|
36
|
+
/** Domain-separation suffix mixed into the reactivity topic. */
|
|
28
37
|
const REACTIVITY_SUFFIX = "reactivity";
|
|
29
38
|
const utf8 = new TextEncoder();
|
|
30
39
|
/**
|
|
31
|
-
* `H(
|
|
32
|
-
* reactivity tree
|
|
33
|
-
*
|
|
34
|
-
* The shared helper consumed by subscriber attachment, origination, and (per-emission) the rotation
|
|
35
|
-
* ticket. `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
|
|
40
|
+
* `H(collectionId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` of a collection's
|
|
41
|
+
* reactivity tree, stable for the collection's life. `collectionId` is the UTF-8 of the id as blocks carry it.
|
|
42
|
+
* `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
|
|
36
43
|
*/
|
|
37
|
-
export function
|
|
44
|
+
export function reactivityCollectionTopicId(collectionId, hash = createRingHash()) {
|
|
38
45
|
const suffixBytes = utf8.encode(REACTIVITY_SUFFIX);
|
|
39
|
-
const input = new Uint8Array(
|
|
40
|
-
input.set(
|
|
41
|
-
input.set(suffixBytes,
|
|
46
|
+
const input = new Uint8Array(collectionId.length + suffixBytes.length);
|
|
47
|
+
input.set(collectionId, 0);
|
|
48
|
+
input.set(suffixBytes, collectionId.length);
|
|
42
49
|
return hash.H(input);
|
|
43
50
|
}
|
|
44
|
-
class HashReactivityTopicAnchor {
|
|
45
|
-
hash;
|
|
46
|
-
constructor(hash) {
|
|
47
|
-
this.hash = hash;
|
|
48
|
-
}
|
|
49
|
-
topicId(tailId) {
|
|
50
|
-
return reactivityTopicId(tailId, this.hash);
|
|
51
|
-
}
|
|
52
|
-
}
|
|
53
51
|
/**
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
52
|
+
* The reactivity root coordinate for a tail: `H(tailId)` over the injected ring hash — the tail block's
|
|
53
|
+
* own ring position, where its storage group sits. `tailId` is the tail's routing key bytes (the raw utf8
|
|
54
|
+
* of the block id, `reactivityTailBytes` on a node), so at the default 256-bit ring width this equals the
|
|
55
|
+
* key network's `hashKey(routingKeyForBlock(tail))` byte for byte; the `topic-bytes-encoding` spec in
|
|
56
|
+
* db-p2p pins that equality. Every party that derives the root group — the notification verifier, the
|
|
57
|
+
* subscriber walk's root step, the forwarder's gossip and recover reads — must start from this one value.
|
|
58
|
+
* It is the one coordinate of a collection's tree that changes when the tail rotates.
|
|
57
59
|
*/
|
|
58
|
-
export function
|
|
59
|
-
return
|
|
60
|
+
export function reactivityRootCoord(tailId, hash = createRingHash()) {
|
|
61
|
+
return createTierAddressing(hash).rootCoord(tailId);
|
|
60
62
|
}
|
|
61
63
|
//# sourceMappingURL=topic-anchor.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"topic-anchor.js","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"topic-anchor.js","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAGrE,gEAAgE;AAChE,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAEvC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAE/B;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,YAAwB,EAAE,OAAkB,cAAc,EAAE;IACvG,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACvE,KAAK,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAkB,EAAE,OAAkB,cAAc,EAAE;IACzF,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC"}
|
|
@@ -2,35 +2,52 @@
|
|
|
2
2
|
* Reactivity — subscriber/forwarder notification verification seam
|
|
3
3
|
* (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
|
|
4
4
|
*
|
|
5
|
-
* A forwarder and a subscriber both verify a notification's threshold signature against the **
|
|
6
|
-
*
|
|
5
|
+
* A forwarder and a subscriber both verify a notification's threshold signature against the **root
|
|
6
|
+
* group's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
|
|
7
7
|
* signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
|
|
8
8
|
* ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
|
|
9
|
-
* cert, so this module is a thin adapter: derive the
|
|
10
|
-
*
|
|
9
|
+
* cert, so this module is a thin adapter: derive the root coordinate from the notification's `tailId`,
|
|
10
|
+
* then hand `(signers, coord, tier, digest, sig)` to the verifier under the root placement rule.
|
|
11
|
+
*
|
|
12
|
+
* **The root group is the tail's storage group** (`docs/reactivity.md` §Origination point). The
|
|
13
|
+
* notification's `tailId` is the base64url of the tail's routing key bytes, so `reactivityRootCoord`
|
|
14
|
+
* of those bytes is the ring position the key network stores the tail block at, and the group there is
|
|
15
|
+
* the one whose commit certificate the notification reuses as its signature. The signature threshold is
|
|
16
|
+
* therefore the **verifier's own** `ceil(|root group| × quorumRatio)` — the formula the commit certificate
|
|
17
|
+
* was captured under — never the cohort-topic `minSigs`, and never a value read from the notification.
|
|
11
18
|
*
|
|
12
19
|
* The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
|
|
13
20
|
* hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
|
|
14
21
|
* as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
|
|
15
22
|
* seam is exposed for bindings that carry signers in a different encoding.
|
|
23
|
+
*
|
|
24
|
+
* **The placement names the tail.** Every `verifyMessage` call carries a {@link RootPlacement} whose
|
|
25
|
+
* `rootKey` is the notification's tail bytes — the same bytes the root coordinate is derived from — so a
|
|
26
|
+
* direct anchor that can fetch the tail's own commit proof (db-p2p's commit-log anchor) knows which block to
|
|
27
|
+
* ask the root group about. Without the key that anchor answers `"unknown"` and a distant verifier is back
|
|
28
|
+
* to trusting the group's certificate on first use, with no other symptom; the verify spec pins the key.
|
|
16
29
|
*/
|
|
17
30
|
import { Tier } from "../cohort-topic/tiers.js";
|
|
18
31
|
import type { IRingHash } from "../cohort-topic/ports.js";
|
|
19
32
|
import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
|
|
20
33
|
import type { NotificationV1 } from "./wire.js";
|
|
21
|
-
/** Verifies a {@link NotificationV1}'s threshold signature against the
|
|
34
|
+
/** Verifies a {@link NotificationV1}'s threshold signature against the root group's membership. */
|
|
22
35
|
export interface NotificationVerifier {
|
|
23
|
-
/** `"verified"` iff `sig` is a valid
|
|
36
|
+
/** `"verified"` iff `sig` is a valid root-group signature over the commit digest, at the placement threshold. */
|
|
24
37
|
verify(n: NotificationV1): Promise<VerifyResult>;
|
|
25
38
|
}
|
|
26
39
|
/** Construction inputs for the default {@link NotificationVerifier}. */
|
|
27
40
|
export interface NotificationVerifierDeps {
|
|
28
41
|
/** The cohort-topic participant-side membership verifier (owns the one fetch-and-retry). */
|
|
29
42
|
readonly verifier: MembershipVerifier;
|
|
30
|
-
/**
|
|
43
|
+
/**
|
|
44
|
+
* The ratio the root group's commit certificates are signed under — this node's own consensus
|
|
45
|
+
* `superMajorityThreshold`, never a value off a message. The threshold applied to a notification is
|
|
46
|
+
* `ceil(|root group| × quorumRatio)`; a ratio outside `(0, 1]` throws here, at construction.
|
|
47
|
+
*/
|
|
48
|
+
readonly quorumRatio: number;
|
|
49
|
+
/** Ring hash for the root-coordinate derivation. Default db-core 256-bit SHA-256. */
|
|
31
50
|
readonly hash?: IRingHash;
|
|
32
|
-
/** Fan-out `F` for tier addressing. Default {@link DEFAULT_FANOUT}. */
|
|
33
|
-
readonly fanout?: number;
|
|
34
51
|
/** Reactivity runs at T3; overridable for tests. */
|
|
35
52
|
readonly tier?: Tier;
|
|
36
53
|
/** Map a wire signer string to the verifier's member-id bytes. Default base64url decode. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAE/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,mGAAmG;AACnG,MAAM,WAAW,oBAAoB;IACpC,iHAAiH;IACjH,MAAM,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACjD;AAED,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACxC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;CACzD;AA2BD,uGAAuG;AACvG,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAE/F"}
|
|
@@ -2,43 +2,58 @@
|
|
|
2
2
|
* Reactivity — subscriber/forwarder notification verification seam
|
|
3
3
|
* (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
|
|
4
4
|
*
|
|
5
|
-
* A forwarder and a subscriber both verify a notification's threshold signature against the **
|
|
6
|
-
*
|
|
5
|
+
* A forwarder and a subscriber both verify a notification's threshold signature against the **root
|
|
6
|
+
* group's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
|
|
7
7
|
* signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
|
|
8
8
|
* ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
|
|
9
|
-
* cert, so this module is a thin adapter: derive the
|
|
10
|
-
*
|
|
9
|
+
* cert, so this module is a thin adapter: derive the root coordinate from the notification's `tailId`,
|
|
10
|
+
* then hand `(signers, coord, tier, digest, sig)` to the verifier under the root placement rule.
|
|
11
|
+
*
|
|
12
|
+
* **The root group is the tail's storage group** (`docs/reactivity.md` §Origination point). The
|
|
13
|
+
* notification's `tailId` is the base64url of the tail's routing key bytes, so `reactivityRootCoord`
|
|
14
|
+
* of those bytes is the ring position the key network stores the tail block at, and the group there is
|
|
15
|
+
* the one whose commit certificate the notification reuses as its signature. The signature threshold is
|
|
16
|
+
* therefore the **verifier's own** `ceil(|root group| × quorumRatio)` — the formula the commit certificate
|
|
17
|
+
* was captured under — never the cohort-topic `minSigs`, and never a value read from the notification.
|
|
11
18
|
*
|
|
12
19
|
* The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
|
|
13
20
|
* hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
|
|
14
21
|
* as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
|
|
15
22
|
* seam is exposed for bindings that carry signers in a different encoding.
|
|
23
|
+
*
|
|
24
|
+
* **The placement names the tail.** Every `verifyMessage` call carries a {@link RootPlacement} whose
|
|
25
|
+
* `rootKey` is the notification's tail bytes — the same bytes the root coordinate is derived from — so a
|
|
26
|
+
* direct anchor that can fetch the tail's own commit proof (db-p2p's commit-log anchor) knows which block to
|
|
27
|
+
* ask the root group about. Without the key that anchor answers `"unknown"` and a distant verifier is back
|
|
28
|
+
* to trusting the group's certificate on first use, with no other symptom; the verify spec pins the key.
|
|
16
29
|
*/
|
|
17
|
-
import { createTierAddressing, DEFAULT_FANOUT } from "../cohort-topic/addressing.js";
|
|
18
30
|
import { createRingHash } from "../cohort-topic/ring-hash.js";
|
|
19
31
|
import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
|
|
20
32
|
import { Tier } from "../cohort-topic/tiers.js";
|
|
21
|
-
import {
|
|
33
|
+
import { createRootPlacement } from "../cohort-topic/sig/threshold.js";
|
|
34
|
+
import { reactivityRootCoord } from "./topic-anchor.js";
|
|
22
35
|
class MembershipNotificationVerifier {
|
|
23
36
|
deps;
|
|
24
|
-
addressing;
|
|
25
37
|
hash;
|
|
26
38
|
tier;
|
|
39
|
+
placement;
|
|
27
40
|
signersToBytes;
|
|
28
41
|
constructor(deps) {
|
|
29
42
|
this.deps = deps;
|
|
30
43
|
this.hash = deps.hash ?? createRingHash();
|
|
31
|
-
this.addressing = createTierAddressing(this.hash, deps.fanout ?? DEFAULT_FANOUT);
|
|
32
44
|
this.tier = deps.tier ?? Tier.T3;
|
|
45
|
+
this.placement = createRootPlacement(deps.quorumRatio);
|
|
33
46
|
this.signersToBytes = deps.signersToBytes ?? b64urlToBytes;
|
|
34
47
|
}
|
|
35
48
|
async verify(n) {
|
|
36
|
-
const
|
|
37
|
-
const expectedCoord = this.
|
|
49
|
+
const tailBytes = b64urlToBytes(n.tailId);
|
|
50
|
+
const expectedCoord = reactivityRootCoord(tailBytes, this.hash);
|
|
38
51
|
const signers = n.signers.map(this.signersToBytes);
|
|
39
52
|
const payload = b64urlToBytes(n.digest);
|
|
40
53
|
const sig = b64urlToBytes(n.sig);
|
|
41
|
-
|
|
54
|
+
// The ratio was validated once at construction; the key is per notification, so spread it per call.
|
|
55
|
+
const placement = { ...this.placement, rootKey: tailBytes };
|
|
56
|
+
return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig, { placement });
|
|
42
57
|
}
|
|
43
58
|
}
|
|
44
59
|
/** Build the default {@link NotificationVerifier} over the cohort-topic {@link MembershipVerifier}. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA2BxD,MAAM,8BAA8B;IAMN;IALZ,IAAI,CAAY;IAChB,IAAI,CAAO;IACX,SAAS,CAAgB;IACzB,cAAc,CAAiC;IAEhE,YAA6B,IAA8B;QAA9B,SAAI,GAAJ,IAAI,CAA0B;QAC1D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,mBAAmB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,aAAa,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,CAAiB;QAC7B,MAAM,SAAS,GAAG,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,aAAa,GAAG,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACjC,oGAAoG;QACpG,MAAM,SAAS,GAAkB,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACzG,CAAC;CACD;AAED,uGAAuG;AACvG,MAAM,UAAU,0BAA0B,CAAC,IAA8B;IACxE,OAAO,IAAI,8BAA8B,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC"}
|
|
@@ -37,7 +37,7 @@ export interface SubscribeAppPayloadV1 {
|
|
|
37
37
|
}
|
|
38
38
|
/** The tail cohort's rotation pre-announce, carried inside (and signed by) a {@link NotificationV1}. */
|
|
39
39
|
export interface RotationHintV1 {
|
|
40
|
-
/** New tail block id the
|
|
40
|
+
/** New tail block id the collection's root is moving to, base64url. */
|
|
41
41
|
newTailId: string;
|
|
42
42
|
/** Revision at which the new tail becomes effective. */
|
|
43
43
|
effectiveAtRevision: number;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/reactivity/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAyBH,+EAA+E;AAC/E,eAAO,MAAM,mCAAmC,QAAY,CAAC;AAI7D,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,cAAc,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;CACtB;AAID,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC9B,
|
|
1
|
+
{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/reactivity/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAyBH,+EAA+E;AAC/E,eAAO,MAAM,mCAAmC,QAAY,CAAC;AAI7D,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,cAAc,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;CACtB;AAID,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC9B,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,mBAAmB,EAAE,MAAM,CAAC;CAC5B;AAED,4HAA4H;AAC5H,MAAM,WAAW,cAAc;IAC9B,CAAC,EAAE,CAAC,CAAC;IACL,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iGAAiG;IACjG,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAgBD,+FAA+F;AAC/F,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAanF;AAED,4GAA4G;AAC5G,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAEpF;AAED,qGAAqG;AACrG,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAE,MAA4C,GAAG,qBAAqB,CAE1I;AAyBD,wFAAwF;AACxF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA4BrE;AAED,sHAAsH;AACtH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAKxF;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,EAAE,eAAe,GAAE,MAAkC,GAAG,UAAU,CAEzH;AAED,6DAA6D;AAC7D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,cAAc,CAEhG"}
|
|
@@ -10,7 +10,7 @@ export type CollectionChangeEvent = {
|
|
|
10
10
|
readonly rev: number;
|
|
11
11
|
/**
|
|
12
12
|
* The collection's chain tail block id at the time of this commit (the `CommitRequest.tailId`).
|
|
13
|
-
*
|
|
13
|
+
* Names the reactivity root (the tail block's storage group, at `H(tailId)`). Present on commit-driven
|
|
14
14
|
* events; `undefined` on read-driven promotions (the `StorageRepo.get` path has no commit tail —
|
|
15
15
|
* those never originate anyway, and are cert-gated out downstream).
|
|
16
16
|
*/
|
package/package.json
CHANGED
|
@@ -19,21 +19,53 @@
|
|
|
19
19
|
* shorter. `F` is the fan-out (default 16, `log₂F = 4`); tier `d` has exactly `F^d` coordinates.
|
|
20
20
|
*
|
|
21
21
|
* The db-p2p binding is responsible for ensuring the coord byte layout (ring width) matches FRET's
|
|
22
|
-
* `RING_BITS` so the
|
|
22
|
+
* `RING_BITS` so the coordinates produced here line up with FRET's ring on the wire.
|
|
23
|
+
*
|
|
24
|
+
* **Routing keys.** Each coordinate is `H(<preimage>)`, and the preimage is what a frame is routed on
|
|
25
|
+
* ({@link TierAddressing.routeKey}): FRET's `routeAct` hashes the key it is handed, once, into the ring
|
|
26
|
+
* position it routes to, so handing it the preimage lands the frame on the coordinate, while handing it the
|
|
27
|
+
* coordinate lands it at `H(coord)`. Every coordinate here is computed as the hash of its route key, so the
|
|
28
|
+
* two cannot drift apart.
|
|
29
|
+
*
|
|
30
|
+
* **Root placement at a routing key** (§Tier addressing → Root placement at a routing key). A topic may
|
|
31
|
+
* name a **root key** — raw bytes, e.g. a block's routing key — and then its tier-0 coordinate is
|
|
32
|
+
*
|
|
33
|
+
* ```
|
|
34
|
+
* coord_0 = H(rootKey)
|
|
35
|
+
* ```
|
|
36
|
+
*
|
|
37
|
+
* instead of `H(0x00 ‖ topicId)`. Tiers `d ≥ 1` are unchanged. The root key is hashed exactly once, with
|
|
38
|
+
* no tier byte in front, so the result is the same ring position the key network derives for that
|
|
39
|
+
* routing key — which is what puts the root on the peers that store the block.
|
|
23
40
|
*/
|
|
24
41
|
|
|
25
|
-
import type { IRingHash, RingCoord } from "./ports.js";
|
|
42
|
+
import type { IRingHash, RingCoord, TopicRouteKey } from "./ports.js";
|
|
26
43
|
|
|
27
|
-
/** Tier-addressing surface — derives the ring coordinate for tier `d` of a topic. */
|
|
44
|
+
/** Tier-addressing surface — derives the ring coordinate for tier `d` of a topic, and the key that routes to it. */
|
|
28
45
|
export interface TierAddressing {
|
|
29
46
|
/** Fan-out per tier (default 16). */
|
|
30
47
|
readonly F: number;
|
|
31
48
|
/** Tier-0 root coordinate: `H(0x00 ‖ topicId)`. Peer-independent. */
|
|
32
49
|
coord0(topicId: Uint8Array): RingCoord;
|
|
50
|
+
/**
|
|
51
|
+
* `H(rootKey)` — the root coordinate of a root-placed topic. Byte-identical to FRET's
|
|
52
|
+
* `hashKey(rootKey)` at the default ring width, so it is the position the key network places that
|
|
53
|
+
* routing key at. Throws `RangeError` on an empty key (no block has an empty routing key).
|
|
54
|
+
*/
|
|
55
|
+
rootCoord(rootKey: Uint8Array): RingCoord;
|
|
33
56
|
/** 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
57
|
coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
|
|
35
|
-
/**
|
|
36
|
-
|
|
58
|
+
/**
|
|
59
|
+
* Dispatches `d === 0` to {@link coord0} — or to {@link rootCoord} when the topic names a `rootKey` —
|
|
60
|
+
* and every other tier to {@link coordD}. A `rootKey` at `d ≥ 1` does not change the coordinate.
|
|
61
|
+
*/
|
|
62
|
+
coord(d: number, peerId: Uint8Array, topicId: Uint8Array, rootKey?: Uint8Array): RingCoord;
|
|
63
|
+
/**
|
|
64
|
+
* The bytes {@link coord} hashes for the same inputs — `0x00 ‖ topicId`, `rootKey`, or
|
|
65
|
+
* `d ‖ prefix(H(P), d·log₂F) ‖ topicId` — which is what a frame for that cohort is routed on: the router
|
|
66
|
+
* hashes it once into the coordinate. Same validation as {@link coord}.
|
|
67
|
+
*/
|
|
68
|
+
routeKey(d: number, peerId: Uint8Array, topicId: Uint8Array, rootKey?: Uint8Array): TopicRouteKey;
|
|
37
69
|
}
|
|
38
70
|
|
|
39
71
|
/** Default fan-out per tier (`log₂16 = 4`). */
|
|
@@ -84,33 +116,61 @@ export class HashTierAddressing implements TierAddressing {
|
|
|
84
116
|
}
|
|
85
117
|
|
|
86
118
|
coord0(topicId: Uint8Array): RingCoord {
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
return this.hash.H(
|
|
119
|
+
return this.hash.H(this.tier0Key(topicId));
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
rootCoord(rootKey: Uint8Array): RingCoord {
|
|
123
|
+
return this.hash.H(this.rootRouteKey(rootKey));
|
|
92
124
|
}
|
|
93
125
|
|
|
94
126
|
coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
|
|
127
|
+
return this.hash.H(this.tierDKey(d, peerId, topicId));
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
coord(d: number, peerId: Uint8Array, topicId: Uint8Array, rootKey?: Uint8Array): RingCoord {
|
|
131
|
+
return this.hash.H(this.routeKey(d, peerId, topicId, rootKey));
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
routeKey(d: number, peerId: Uint8Array, topicId: Uint8Array, rootKey?: Uint8Array): TopicRouteKey {
|
|
135
|
+
if (d !== 0) {
|
|
136
|
+
return this.tierDKey(d, peerId, topicId);
|
|
137
|
+
}
|
|
138
|
+
return rootKey === undefined ? this.tier0Key(topicId) : this.rootRouteKey(rootKey);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** `0x00 ‖ topicId` — the preimage of {@link coord0}. */
|
|
142
|
+
private tier0Key(topicId: Uint8Array): TopicRouteKey {
|
|
143
|
+
const key = new Uint8Array(1 + topicId.length);
|
|
144
|
+
key[0] = 0x00;
|
|
145
|
+
key.set(topicId, 1);
|
|
146
|
+
return key as TopicRouteKey;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/** The root key itself — the preimage of {@link rootCoord}, hashed with no tier byte in front. */
|
|
150
|
+
private rootRouteKey(rootKey: Uint8Array): TopicRouteKey {
|
|
151
|
+
if (rootKey.length === 0) {
|
|
152
|
+
throw new RangeError("a root key must be non-empty");
|
|
153
|
+
}
|
|
154
|
+
return rootKey as TopicRouteKey;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** `d ‖ prefix(H(P), d·log₂F) ‖ topicId` — the preimage of {@link coordD}. */
|
|
158
|
+
private tierDKey(d: number, peerId: Uint8Array, topicId: Uint8Array): TopicRouteKey {
|
|
95
159
|
if (!Number.isInteger(d) || d < 1) {
|
|
96
|
-
throw new RangeError(`
|
|
160
|
+
throw new RangeError(`a tier-d coordinate requires an integer d ≥ 1, got ${d}`);
|
|
97
161
|
}
|
|
98
162
|
if (d > 255) {
|
|
99
163
|
throw new RangeError(`tier d must fit in one byte (≤ 255), got ${d}`);
|
|
100
164
|
}
|
|
101
|
-
//
|
|
102
|
-
// NOTE: re-hashes peerId on every
|
|
103
|
-
//
|
|
165
|
+
// Ring-hash P first so the shard input is uniform.
|
|
166
|
+
// NOTE: re-hashes peerId on every call; a walk over a tier ladder recomputes H(self) per tier.
|
|
167
|
+
// Negligible today (walk steps are network-bound); if coord becomes hot, cache H(peerId).
|
|
104
168
|
const prefix = prefixBits(this.hash.H(peerId), d * this.log2F);
|
|
105
|
-
const
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
return
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
|
|
113
|
-
return d === 0 ? this.coord0(topicId) : this.coordD(d, peerId, topicId);
|
|
169
|
+
const key = new Uint8Array(1 + prefix.length + topicId.length);
|
|
170
|
+
key[0] = d;
|
|
171
|
+
key.set(prefix, 1);
|
|
172
|
+
key.set(topicId, 1 + prefix.length);
|
|
173
|
+
return key as TopicRouteKey;
|
|
114
174
|
}
|
|
115
175
|
}
|
|
116
176
|
|