@ghostlytools/sdk 0.0.0-stage → 1.2.3

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.
Files changed (145) hide show
  1. package/README.md +13 -2
  2. package/dist/app.js +67 -0
  3. package/dist/app.js.map +1 -0
  4. package/dist/core.js +207 -0
  5. package/dist/core.js.map +1 -0
  6. package/dist/fakes-CBIuqo5e.js +536 -0
  7. package/dist/fakes-CBIuqo5e.js.map +1 -0
  8. package/dist/fakes.js +2 -0
  9. package/dist/index.js +179 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/keet-identity-key-BylxCPl4.js +76483 -0
  12. package/dist/keet-identity-key-BylxCPl4.js.map +1 -0
  13. package/dist/src-DCeLPsi-.js +31056 -0
  14. package/dist/src-DCeLPsi-.js.map +1 -0
  15. package/dist/testing.js +330 -0
  16. package/dist/testing.js.map +1 -0
  17. package/dist/types/browser/src/engine/paymentAdapters/providers/contractSuite.d.ts +41 -0
  18. package/dist/types/browser/src/engine/paymentAdapters/providers/lightning.d.ts +103 -0
  19. package/dist/types/browser/src/engine/paymentAdapters/providers/onchain.d.ts +88 -0
  20. package/dist/types/browser/src/engine/paymentAdapters/providers/testing.d.ts +89 -0
  21. package/dist/types/browser/src/engine/paymentAdapters/providers/types.d.ts +151 -0
  22. package/dist/types/browser/src/plugins/bundled.d.ts +8 -0
  23. package/dist/types/browser/src/plugins/registry.d.ts +57 -0
  24. package/dist/types/browser/src/proofs/contract.d.ts +262 -0
  25. package/dist/types/browser/src/proofs/contractSuite.d.ts +27 -0
  26. package/dist/types/browser/src/proofs/testing.d.ts +36 -0
  27. package/dist/types/browser/src/proofs/verify.d.ts +23 -0
  28. package/dist/types/browser/src/shared/mints.d.ts +50 -0
  29. package/dist/types/core/src/appBundle.d.ts +173 -0
  30. package/dist/types/core/src/appStatements.d.ts +142 -0
  31. package/dist/types/core/src/appStore.d.ts +133 -0
  32. package/dist/types/core/src/appUpdates.d.ts +88 -0
  33. package/dist/types/core/src/atprotoIdentity.d.ts +49 -0
  34. package/dist/types/core/src/atprotoRepo.d.ts +101 -0
  35. package/dist/types/core/src/avatar.d.ts +19 -0
  36. package/dist/types/core/src/bip322.d.ts +57 -0
  37. package/dist/types/core/src/bitcoinAddress.d.ts +5 -0
  38. package/dist/types/core/src/bitcoinMessage.d.ts +15 -0
  39. package/dist/types/core/src/bitcoinScript.d.ts +69 -0
  40. package/dist/types/core/src/bolt11.d.ts +30 -0
  41. package/dist/types/core/src/bytes.d.ts +11 -0
  42. package/dist/types/core/src/callSignal.d.ts +232 -0
  43. package/dist/types/core/src/canonicalJson.d.ts +22 -0
  44. package/dist/types/core/src/capsRecord.d.ts +234 -0
  45. package/dist/types/core/src/catchUp.d.ts +45 -0
  46. package/dist/types/core/src/chatFiles.d.ts +271 -0
  47. package/dist/types/core/src/clockWatch.d.ts +72 -0
  48. package/dist/types/core/src/communityRendezvous.d.ts +113 -0
  49. package/dist/types/core/src/crypto.d.ts +10 -0
  50. package/dist/types/core/src/datalink.d.ts +187 -0
  51. package/dist/types/core/src/deviceInvite.d.ts +51 -0
  52. package/dist/types/core/src/deviceLink.d.ts +70 -0
  53. package/dist/types/core/src/dhtDelivery.d.ts +403 -0
  54. package/dist/types/core/src/dhtFiles.d.ts +46 -0
  55. package/dist/types/core/src/did.d.ts +134 -0
  56. package/dist/types/core/src/didDht.d.ts +155 -0
  57. package/dist/types/core/src/directPath.d.ts +63 -0
  58. package/dist/types/core/src/dns.d.ts +41 -0
  59. package/dist/types/core/src/domainProofs.d.ts +88 -0
  60. package/dist/types/core/src/engineErrors.d.ts +90 -0
  61. package/dist/types/core/src/enroll.d.ts +98 -0
  62. package/dist/types/core/src/files.d.ts +73 -0
  63. package/dist/types/core/src/forwards.d.ts +12 -0
  64. package/dist/types/core/src/frames.d.ts +211 -0
  65. package/dist/types/core/src/ghostlink.d.ts +1510 -0
  66. package/dist/types/core/src/groupCommits.d.ts +103 -0
  67. package/dist/types/core/src/groupCommunity.d.ts +714 -0
  68. package/dist/types/core/src/groupCrypto.d.ts +60 -0
  69. package/dist/types/core/src/groupEdits.d.ts +67 -0
  70. package/dist/types/core/src/groupEntry.d.ts +61 -0
  71. package/dist/types/core/src/groupFiles.d.ts +106 -0
  72. package/dist/types/core/src/groupHubs.d.ts +61 -0
  73. package/dist/types/core/src/groupMentions.d.ts +27 -0
  74. package/dist/types/core/src/groupMeta.d.ts +162 -0
  75. package/dist/types/core/src/groupSession.d.ts +710 -0
  76. package/dist/types/core/src/groupSignals.d.ts +167 -0
  77. package/dist/types/core/src/groupTyping.d.ts +56 -0
  78. package/dist/types/core/src/groupWake.d.ts +68 -0
  79. package/dist/types/core/src/handoff.d.ts +255 -0
  80. package/dist/types/core/src/http.d.ts +125 -0
  81. package/dist/types/core/src/identity.d.ts +17 -0
  82. package/dist/types/core/src/identityProofs.d.ts +243 -0
  83. package/dist/types/core/src/identityTimeline.d.ts +72 -0
  84. package/dist/types/core/src/image.d.ts +33 -0
  85. package/dist/types/core/src/index.d.ts +100 -0
  86. package/dist/types/core/src/invite.d.ts +128 -0
  87. package/dist/types/core/src/link.d.ts +353 -0
  88. package/dist/types/core/src/linkPreview.d.ts +60 -0
  89. package/dist/types/core/src/linkTrace.d.ts +12 -0
  90. package/dist/types/core/src/lnurl.d.ts +99 -0
  91. package/dist/types/core/src/messageTime.d.ts +28 -0
  92. package/dist/types/core/src/miniApp.d.ts +141 -0
  93. package/dist/types/core/src/pairedApps.d.ts +151 -0
  94. package/dist/types/core/src/pairedCalls.d.ts +59 -0
  95. package/dist/types/core/src/pairedCapabilities.d.ts +101 -0
  96. package/dist/types/core/src/pairedEdits.d.ts +83 -0
  97. package/dist/types/core/src/pairedFiles.d.ts +30 -0
  98. package/dist/types/core/src/pairedHttp.d.ts +15 -0
  99. package/dist/types/core/src/pairedSession.d.ts +163 -0
  100. package/dist/types/core/src/pairedSignal.d.ts +17 -0
  101. package/dist/types/core/src/pairedTransports.d.ts +76 -0
  102. package/dist/types/core/src/pairedTyping.d.ts +130 -0
  103. package/dist/types/core/src/pairedWake.d.ts +109 -0
  104. package/dist/types/core/src/pairingProgress.d.ts +107 -0
  105. package/dist/types/core/src/paymentIntent.d.ts +111 -0
  106. package/dist/types/core/src/paymentUri.d.ts +34 -0
  107. package/dist/types/core/src/payments.d.ts +97 -0
  108. package/dist/types/core/src/peerProofs.d.ts +98 -0
  109. package/dist/types/core/src/pins.d.ts +73 -0
  110. package/dist/types/core/src/pkarr.d.ts +48 -0
  111. package/dist/types/core/src/pkdns.d.ts +35 -0
  112. package/dist/types/core/src/pubkyProofs.d.ts +25 -0
  113. package/dist/types/core/src/pubkyRing.d.ts +21 -0
  114. package/dist/types/core/src/reactions.d.ts +108 -0
  115. package/dist/types/core/src/records.d.ts +89 -0
  116. package/dist/types/core/src/relay.d.ts +437 -0
  117. package/dist/types/core/src/relayBreaker.d.ts +99 -0
  118. package/dist/types/core/src/replies.d.ts +41 -0
  119. package/dist/types/core/src/services.d.ts +35 -0
  120. package/dist/types/core/src/setUpdate.d.ts +53 -0
  121. package/dist/types/core/src/signal.d.ts +53 -0
  122. package/dist/types/core/src/signer.d.ts +13 -0
  123. package/dist/types/core/src/sparkAddress.d.ts +37 -0
  124. package/dist/types/core/src/sshsig.d.ts +74 -0
  125. package/dist/types/core/src/statusCards.d.ts +253 -0
  126. package/dist/types/core/src/storeForward.d.ts +144 -0
  127. package/dist/types/core/src/text.d.ts +20 -0
  128. package/dist/types/core/src/transport.d.ts +151 -0
  129. package/dist/types/core/src/transportSwitch.d.ts +160 -0
  130. package/dist/types/core/src/turnRead.d.ts +145 -0
  131. package/dist/types/core/src/turnRecord.d.ts +165 -0
  132. package/dist/types/core/src/version.d.ts +9 -0
  133. package/dist/types/core/src/video.d.ts +44 -0
  134. package/dist/types/core/src/voice.d.ts +88 -0
  135. package/dist/types/core/src/webPush.d.ts +58 -0
  136. package/dist/types/sdk/src/app.d.ts +23 -0
  137. package/dist/types/sdk/src/core.d.ts +7 -0
  138. package/dist/types/sdk/src/fakes.d.ts +6 -0
  139. package/dist/types/sdk/src/index.d.ts +26 -0
  140. package/dist/types/sdk/src/testing.d.ts +7 -0
  141. package/dist/types-DvtCy3WB.js +99 -0
  142. package/dist/types-DvtCy3WB.js.map +1 -0
  143. package/dist/verify-DBGw6wYt.js +106 -0
  144. package/dist/verify-DBGw6wYt.js.map +1 -0
  145. package/package.json +70 -4
@@ -0,0 +1,89 @@
1
+ import { type GhostRecord, type SignedPacket } from "./pkarr.js";
2
+ import { type ServiceAd } from "./services.js";
3
+ /**
4
+ * TXT labels a peer publishes under its own key. Every value except `_ts` and
5
+ * `_ack` is secretbox-encrypted with the link key.
6
+ *
7
+ * `_msgs`, `_ts`, `_ack`, `_nick` and `_call` are the original Ghost protocol.
8
+ * `_svc` and `_rtc` are additive: clients that predate them ignore unknown
9
+ * labels, so old and new peers keep chatting and calling each other.
10
+ */
11
+ export declare const LABEL: {
12
+ readonly msgs: "_msgs";
13
+ readonly ts: "_ts";
14
+ readonly ack: "_ack";
15
+ readonly nick: "_nick";
16
+ readonly call: "_call";
17
+ /** Service advertisement, see `services.ts`. */
18
+ readonly svc: "_svc";
19
+ /** Signaling for the WebRTC data link, see `signal.ts`. */
20
+ readonly rtc: "_rtc";
21
+ /**
22
+ * A group link's layer-1 transports and how to dial its native ones (`encodePacketTransports` in `capsRecord.ts`):
23
+ * published only by an app with no WebRTC and by a member answering one, so two apps that have WebRTC never send it.
24
+ */
25
+ readonly tr: "_tr";
26
+ };
27
+ export declare const RECORD_TTL = 300;
28
+ /** Same ceiling the Rust implementation applies to the encrypted message batch. */
29
+ export declare const MAX_MSGS_PAYLOAD_B64 = 800;
30
+ export interface CompactMessage {
31
+ t: number;
32
+ m: string;
33
+ }
34
+ export interface OutgoingLinkState {
35
+ messages: CompactMessage[];
36
+ ackTimestamp: number;
37
+ nick?: string;
38
+ callSignal?: string | null;
39
+ rtcSignal?: string | null;
40
+ /** `undefined` publishes no `_svc` at all, which is what a legacy peer looks like. */
41
+ services?: ServiceAd[];
42
+ /** A group link's `_tr` value, already encoded; absent publishes none. */
43
+ transports?: string | null;
44
+ }
45
+ export interface BuiltLinkRecords {
46
+ records: GhostRecord[];
47
+ /** How many of the newest messages made it into the packet. */
48
+ keptMessages: number;
49
+ /** False when the advertisement had to be left out to fit the packet. */
50
+ servicesIncluded: boolean;
51
+ }
52
+ /**
53
+ * The packet an inviter puts under the contact's key before they join, so that their first packet lands
54
+ * as a newer one under a key the network already knows (seconds faster than a first packet under a
55
+ * fresh key). It carries no message record, which every link session's own packet does, even empty:
56
+ * that is how a reader tells it from a contact who is here (or was, and left without a word).
57
+ */
58
+ export declare function emptyLinkRecords(): GhostRecord[];
59
+ /** A packet nobody's link session published (see `emptyLinkRecords`): read as no packet at all. */
60
+ export declare function isEmptyLinkPacket(batch: ResolvedLink): boolean;
61
+ /**
62
+ * Builds the records for one publish. A Pkarr packet is at most 1000 bytes, so
63
+ * space is handed out by priority: signaling first (it is what gets peers onto
64
+ * WebRTC, where there is no such limit), then the service advertisement, then
65
+ * as many of the newest messages as still fit.
66
+ */
67
+ export declare function buildLinkRecords(pubKeyZ32: string, state: OutgoingLinkState, encKey: Uint8Array): BuiltLinkRecords;
68
+ export interface ResolvedMessage {
69
+ text: string;
70
+ timestamp: number;
71
+ nick?: string;
72
+ }
73
+ export interface ResolvedLink {
74
+ messages: ResolvedMessage[];
75
+ latestTimestamp: number;
76
+ peerAck: number;
77
+ nick?: string;
78
+ callSignal: string | null;
79
+ rtcSignal: string | null;
80
+ /** `null` when the peer published no advertisement (legacy client or offline). */
81
+ services: ServiceAd[] | null;
82
+ /** A group link's `_tr` value as published (`parsePacketTransports`); `null` when there is none. */
83
+ transports: string | null;
84
+ rawRecordNames: string[];
85
+ encryptedPayloadLength: number;
86
+ /** Milliseconds since the UNIX epoch. */
87
+ packetTimestamp: number;
88
+ }
89
+ export declare function parseLinkRecords(packet: SignedPacket, encKey: Uint8Array): ResolvedLink;
@@ -0,0 +1,437 @@
1
+ import type { Identity } from "./identity.js";
2
+ import { type GhostRecord, type SignedPacket } from "./pkarr.js";
3
+ import { type DiscoveryStatus, type RelayBreakerOptions } from "./relayBreaker.js";
4
+ import { type DiscoveryChange, type PkarrRequestOptions, type PkarrTransport, type ServerTime } from "./transport.js";
5
+ import type { TurnConditions, TurnSourceAnswer, TurnSourcePut } from "./turnRead.js";
6
+ /**
7
+ * Public Pkarr relays. They are generic Pkarr infrastructure (an HTTP bridge to
8
+ * the Mainline DHT), not a Ghostly backend: they only ever see signed,
9
+ * encrypted packets. Every client uses this list: the browser clients read and
10
+ * write through it, Ghostly Desktop writes to it (so browser contacts see its
11
+ * packets) and reads from it only when "Also use Pkarr relays" is on. Adding a
12
+ * relay is one line here; see docs/RELAYS.md for how one is chosen.
13
+ */
14
+ export declare const DEFAULT_RELAYS: string[];
15
+ /**
16
+ * Relay lists that were the defaults once: a profile that still has one gets today's defaults. When a relay
17
+ * joins `DEFAULT_RELAYS`, the list as it was goes here, so profiles on the old defaults move with it.
18
+ */
19
+ export declare const PREVIOUS_DEFAULT_RELAYS: string[][];
20
+ /** The defaults for `relays` when it is one of the old default lists, `relays` itself otherwise. */
21
+ export declare function currentRelays(relays: string[]): string[];
22
+ /**
23
+ * Requests this client allows itself per relay and minute. Relays limit by IP
24
+ * (120 a minute when this was written) and one address is often shared by
25
+ * several peers: two browser profiles, a tab and an extension, a household.
26
+ */
27
+ export declare const REQUESTS_PER_MINUTE = 30;
28
+ /**
29
+ * Of those, what background requests (`{ background: true }`: periodic looks at shared records, as a
30
+ * community group's hub makes) may spend, counted on their own: the rest is kept for links, whose
31
+ * signaling cannot wait, and a burst of signaling does not hold the background ones back afterwards.
32
+ */
33
+ export declare const BACKGROUND_REQUESTS_PER_MINUTE = 20;
34
+ /**
35
+ * A link's write the budget refused (its presence, its offer, its answer) goes first when the minute
36
+ * frees a request: reads on that relay wait this long after the refusal. A link that polls fast for a
37
+ * peer while its offer waits would otherwise take every request the minute frees, and the offer (the
38
+ * only thing that peer is waiting for) would go out only once the polling slowed down, half a minute later.
39
+ */
40
+ export declare const WRITE_FIRST_MS = 5000;
41
+ /**
42
+ * Once a 1:1 chat needs the relays (the budget refused one of its requests there, or it read urgently anywhere: it polls
43
+ * fast for a signal due any moment), group requests leave it the last this many of each minute, for a minute. Groups
44
+ * that spend the whole budget spend it over the minute, so the chat then takes the next request that frees, within
45
+ * seconds, and has room for what follows (the receipt). Waiting for a refusal was too late when a contact went away
46
+ * from a chat and from groups at once: the chat and the groups' edges all watched fast for it, the edges spent both
47
+ * relays' minute in 40 s, and the chat read the contact's offer half a minute late (2026-09-27). A chat with nothing
48
+ * to wait for leaves groups the whole budget: a community door alone costs about 22 requests a minute, and a reserve
49
+ * kept for any chat starved a new group's edges. The reserve is per chat: a chat that reads its contact at a slow pace
50
+ * again (it is live) gives its part back at once. Kept for the minute, a daemon back after a restart with its chats
51
+ * live in 18 s held a group's edge that had just missed its read for 48 s more (bug hunt r6a, 2026-09-29).
52
+ */
53
+ export declare const CHAT_RESERVE = 10;
54
+ /**
55
+ * A 1:1 chat's signaling (a new offer or answer, and its reads for the answer to its offer, `signal`) may go over a
56
+ * relay's minute by this fraction of it: 6 on a relay of 30, 12 on one of 60, 1 on relay.pkarr.org's 5 (it allows 10),
57
+ * and never more than that in any minute; its reads leave the last of those to a write. Everything else still stops at
58
+ * the limit. The minute before a chat leaves DHT only can be spent by then (the pairing, the texts over the DHT), and
59
+ * its offer or answer, the one thing the contact waits for, then waited 40 s for requests to age out while the
60
+ * contact's attempt gave up: the matrix's extension chat stayed "On DHT · retrying live" 46 times in 120 (2026-09-30).
61
+ */
62
+ export declare const SIGNALING_ALLOWANCE_SHARE: number;
63
+ /**
64
+ * A 1:1 chat's reads of a contact that went away from a live session, in their first seconds (`departed`,
65
+ * `DEPARTED_READ_MS` in link.ts), may go over a relay's minute within the chat's allowance (`SIGNALING_ALLOWANCE_SHARE`):
66
+ * at most this many of each contact's in a minute, every relay together, leaving the last of the allowance to an offer or
67
+ * answer. Their fast poll reads every 2 s, on the relays in turn: 6 cover 12 s from the goodbye, by when an app that
68
+ * restarts has its offer out (2.5 to 10 s in the lab of #1441), and add at most 3 to a relay's minute. They wait for no
69
+ * write the minute refused: that write cannot go before the minute frees anyway. A daemon restarted 20 s after its last
70
+ * restart found its contact's minute spent on both relays: every read of it was held back, the offer it published as it
71
+ * came up was never read, and the chat came back only through the race's DHT dial, 8 s on (2026-10-07).
72
+ */
73
+ export declare const DEPARTED_READS = 6;
74
+ /**
75
+ * A group edge's requests for a member that may be back may go over a relay's minute by this fraction of it (4 on a
76
+ * relay of 30, 8 on one of 60, none on relay.pkarr.org's 5): its reads of a member that went away and its packet
77
+ * written meanwhile, which that member reads first when it is back (`watch`), its offer or answer, and its reads for
78
+ * the answer to its offer (`signal`). Its reads leave the last of those to a write and go
79
+ * one at a time (`GROUP_OVER_PACE_MS`), so the allowance lasts until the member is back, and the read that finds its
80
+ * offer still has the answer behind it. Less than a chat's (`SIGNALING_ALLOWANCE_SHARE`), which keeps room past the
81
+ * groups'. A private group's admin that had just let members in and seen them restart had spent its minute in 30 s;
82
+ * a member back then, with no other member online to carry its offer, had it read only when the minute freed: 18 to
83
+ * 42 s later, one round in four of the member-back runs (2026-10-03).
84
+ */
85
+ export declare const GROUP_SIGNALING_ALLOWANCE_SHARE: number;
86
+ /** Past the limit, a group's reads within its allowance go no more often than this on a relay. */
87
+ export declare const GROUP_OVER_PACE_MS = 5000;
88
+ /**
89
+ * Groups' urgent reads (their edges looking fast for a signal) take at most a quarter of a relay's minute in any this
90
+ * long, so that they never spend it in a burst. An app back after a restart has every edge offering and looking fast at
91
+ * once; the members at the other end answer only once they notice its old sessions went (about 20 s with
92
+ * node-datachannel). On the default relays the edges spent the groups' share of the minute in those seconds, and read
93
+ * nothing for 40 s more: a private group's edges were live again 75 to 110 s after a restart (bug hunt r5a, 2026-09-29).
94
+ */
95
+ export declare const GROUP_BURST_MS = 15000;
96
+ /** …and never fewer than one link polling fast (every 2 s) reads in that time: one edge alone is never held back. */
97
+ export declare const GROUP_BURST_ONE_LINK = 8;
98
+ /**
99
+ * A group's edges' reads of members that went away from a live session and have not shown themselves back (`watch`: a
100
+ * link looks for them closely for two minutes, `WATCH_PEER_MS`) take at most this share of a relay's requests, whatever
101
+ * their number, spread over the minute (`GROUP_RATION_WINDOW_MS`): 2 in any 10 s on a relay of 30. Under it, the key
102
+ * read longest ago goes first. A member alone in a private group whose three other members left at once watched each of
103
+ * them every 2 s: those reads and the admin's knock poll spent both relays' minute, the member back first had its offer
104
+ * read only when the minute freed, 25 to 44 s on, and its edge came up then (bug hunt r12, measured again 2026-10-03).
105
+ */
106
+ export declare const WATCH_SHARE: number;
107
+ /**
108
+ * Once a group's read found a relay's minute full, the groups' reads there are spread over the minute for a minute
109
+ * (`GROUP_RATION_MS`): at most a sixth of it in any 10 s (5 on a relay of 30), the key read longest ago first. A sliding
110
+ * minute that demand keeps full hands out its requests in bursts: the minute is spent in 25 to 35 s as requests age
111
+ * out, then nothing frees for the rest of it. A private group's admin (its knock poll every 2 s while its link is new)
112
+ * whose members left and came back read nothing for 18 to 42 s at a time, and the member back first waited that long
113
+ * for its edge (bug hunt r12, measured again on 2026-10-03). Writes are not counted: they go first anyway.
114
+ */
115
+ export declare const GROUP_RATION_WINDOW_MS = 10000;
116
+ /**
117
+ * While a link polls fast (an `urgent` read: its peer, or the peer's offer or answer, is due any moment) within this
118
+ * long, background requests (a community's periodic looks) are held to `BACKGROUND_WHILE_SIGNALING` a minute on each
119
+ * relay rather than their usual share. A fast poll reads every 2 s, one relay after the other.
120
+ */
121
+ export declare const SIGNALING_WINDOW_MS = 10000;
122
+ /**
123
+ * Background requests a minute on each relay while a link signals: one look every 12 s. Next to a community's
124
+ * lookups (20 a minute), a new group edge on one relay got 10 and read every 6 s, and its offer and answer missed each
125
+ * other's fast windows (2026-09-27). Not none: fast windows can follow one another, and a hub still reads its knocks.
126
+ */
127
+ export declare const BACKGROUND_WHILE_SIGNALING = 5;
128
+ /**
129
+ * A read of a key the relays answered this recently is answered from that answer, with no request. Several parts of
130
+ * a chat read the contact's keys (the link's poll, its capabilities, DHT delivery), and each tends to read again
131
+ * within a few dozen milliseconds of its last read, when a pace changes or a signal goes out: nothing new can be there
132
+ * yet, and a pairing spent a sixth of its requests on those reads (2026-09-27). A publish under the key forgets it.
133
+ */
134
+ export declare const FRESH_READ_MS = 500;
135
+ /**
136
+ * Relays whose limit per address is far from the others': this client's share of theirs, a minute, in place of
137
+ * `REQUESTS_PER_MINUTE`. relay.pkarr.org (not a default, see docs/RELAYS.md) allows 10 (`x-ratelimit-limit`), which a
138
+ * browser cannot read without CORS exposing it. pkarr.pubky.app allows 1000 (pkarr.pubky.org, on the same address,
139
+ * 50): 60 of ours leaves room for many peers behind one address, and a page that pairs three contacts in a minute,
140
+ * about ten requests a relay each, still has requests to spare there (2026-09-28). Writes go to every relay and
141
+ * count once one took them; reads go to a relay with requests left.
142
+ */
143
+ export declare const RELAY_REQUESTS_PER_MINUTE: Record<string, number>;
144
+ /**
145
+ * A read asks the next relay too when the one it asked has not answered within this long, and takes the first good
146
+ * answer. Measured on 2026-10-03 from a home connection: a relay hands over a packet it holds in 0.25 s (0.7 s on a new
147
+ * connection), and one that has to fetch the packet from the DHT first takes 2.7 s. Reads used to wait for a relay's
148
+ * answer before asking the next one, up to the 10 s timeout: a relay that answered slowly or not at all (pkarr.pubky.org
149
+ * on 2026-10-03) made every read of a pairing that slow, and the pairing never finished.
150
+ */
151
+ export declare const HEDGE_MS = 1500;
152
+ /**
153
+ * The hedge delay for a key whose last read found nothing (404): a relay takes 3 to 5 s to say so (it asks the DHT
154
+ * every time), and a hedge at `HEDGE_MS` would double every poll of a key nobody has published yet.
155
+ */
156
+ export declare const HEDGE_MISSING_MS = 6000;
157
+ /**
158
+ * A packet that took longer than this to arrive, or a hedge lost to a relay that answered with the packet, is slow: it
159
+ * counts against the relay's breaker like a failure (three in a row trip it, logged as "slow"), while another relay is
160
+ * there to ask. A 404 says nothing either way: every relay is slow to give one.
161
+ */
162
+ export declare const SLOW_MS = 3000;
163
+ /** A relay found slow goes after the others in every read for this long, unless it answers fast meanwhile. */
164
+ export declare const SLOW_DEMOTE_MS = 60000;
165
+ /** How long each source has to answer a read or a put of the turn record (WISP 06 § Publishing and reading). */
166
+ export declare const TURN_SOURCE_TIMEOUT_MS = 8000;
167
+ export interface RelayTransportOptions {
168
+ relays?: string[];
169
+ timeoutMs?: number;
170
+ fetch?: typeof fetch;
171
+ /**
172
+ * Requests allowed per relay and minute (`REQUESTS_PER_MINUTE`); background ones get a share of it.
173
+ * `Infinity` for relays of one's own, with no limit to stay under (a test's relay in the same process).
174
+ */
175
+ requestsPerMinute?: number;
176
+ /** How long a read answers the next ones of the same key (`FRESH_READ_MS`); 0 makes every read a request. */
177
+ freshReadMs?: number;
178
+ /** `HEDGE_MS`; `Infinity` asks the next relay only once the one asked failed. */
179
+ hedgeMs?: number;
180
+ /** The circuit breaker's settings (tests shorten its waits); trips are logged with `log`. */
181
+ breaker?: RelayBreakerOptions;
182
+ /** Where a relay that trips or recovers is reported; never with a key. `console.info` by default. */
183
+ log?: (line: string) => void;
184
+ }
185
+ export declare function normalizeRelayUrl(input: string): string | null;
186
+ export declare class RelayTransport implements PkarrTransport {
187
+ private relays;
188
+ private readonly timeoutMs;
189
+ private readonly fetchFn;
190
+ private readonly timeListeners;
191
+ private readonly lastTimestamp;
192
+ private readonly newest;
193
+ /**
194
+ * The latest time of any packet read under a key, whoever dated it: the next packet this client puts there is dated
195
+ * past it (`nextTimestamp`). A key is not always one writer's with one clock: a group's lobby, beacon and knock
196
+ * records are written by every member, an inviter warms its contact's key with an empty packet, and this device's
197
+ * own clock may have been set back since it last wrote. A relay and the DHT keep only the packet dated latest, so
198
+ * one dated by this clock alone, when it is behind, was refused (409) or silently never read, until this clock
199
+ * caught up with the other one: minutes, or an hour.
200
+ */
201
+ private readonly seenTimestamp;
202
+ /**
203
+ * The last packet this client put under a key that a relay took. A read the budget holds back answers the newer of
204
+ * it and the last one read: a hub that wrote its own beacon entry since it last read the beacon must not see that
205
+ * entry as old as the one it replaced (it would stop counting itself at its community's door until its next write).
206
+ */
207
+ private readonly written;
208
+ private readonly coolingDown;
209
+ private readonly networkCooldown;
210
+ private cursor;
211
+ /** Per key, the relay that answered its last read: the next read of the key starts at the one after it (`resolve`). */
212
+ private readonly lastReadFrom;
213
+ private readonly spent;
214
+ private readonly spentBackground;
215
+ /** Groups' urgent reads on each relay in the last `GROUP_BURST_MS`. */
216
+ private readonly spentGroupUrgent;
217
+ /** Watch reads on each relay in the last `GROUP_RATION_WINDOW_MS` (`WATCH_SHARE`). */
218
+ private readonly spentWatch;
219
+ /** Groups' reads past the limit on each relay in the last `GROUP_OVER_PACE_MS` (`GROUP_SIGNALING_ALLOWANCE_SHARE`). */
220
+ private readonly spentGroupOver;
221
+ /** Per contact, its departed reads past the limit in the last minute, every relay together (`DEPARTED_READS`). */
222
+ private readonly departedOver;
223
+ /**
224
+ * Per key a group reads (not in the background), when a read of it last went out and when it last asked: whose turn
225
+ * it is under the watch share (`WATCH_SHARE`) and while the groups' reads are rationed (`GROUP_RATION_WINDOW_MS`).
226
+ */
227
+ private readonly readTurns;
228
+ /** Groups' reads (not background ones) on each relay in the last `GROUP_RATION_WINDOW_MS`. */
229
+ private readonly spentGroupReads;
230
+ /** When a group's read last found each relay's minute full: its reads there are rationed for `GROUP_RATION_MS`. */
231
+ private readonly groupsFullAt;
232
+ /** When a link's write was last refused on each relay (`chat <relay>`, `group <relay>`), while it waits for the budget. */
233
+ private readonly writeWaiting;
234
+ /**
235
+ * Per key a 1:1 chat asks for: when it last read urgently (for the next minute, groups leave it `CHAT_RESERVE` on
236
+ * every relay) and when the budget last refused it on each relay (the same, on that relay). A read of the key at a
237
+ * slow pace (the chat is live, or back in the background) drops it: `CHAT_RESERVE`.
238
+ */
239
+ private readonly chatNeeds;
240
+ /** When a link (a chat's or a group's) last asked urgently: background requests yield for `SIGNALING_WINDOW_MS`. */
241
+ private urgentAt;
242
+ /** Timestamp of the last packet sent to each relay, per key: the compare-and-swap value for the next one. */
243
+ private readonly lastPut;
244
+ /** Per relay and key, the newest packet that relay held back for its budget while another relay took it (`catchUpLater`). */
245
+ private readonly catchUp;
246
+ private catchUpTimer;
247
+ /** When the relays last answered a read of each key, for `FRESH_READ_MS`. */
248
+ private readonly readAt;
249
+ private readonly freshReadMs;
250
+ private readonly perMinute;
251
+ /** `requestsPerMinute` was given: it bounds every relay, one with its own share (`RELAY_REQUESTS_PER_MINUTE`) too. */
252
+ private readonly perMinuteGiven;
253
+ private readonly backgroundPerMinute;
254
+ private readonly backgroundWhileSignaling;
255
+ private readonly breaker;
256
+ /** The relay the last read was answered by. */
257
+ private lastRelay;
258
+ private readonly hedgeMs;
259
+ /** Until when each relay found slow (`SLOW_MS`) goes after the others in a read (`readOrder`). */
260
+ private readonly slowUntil;
261
+ /** Keys whose last read was answered 404: their next read hedges later (`HEDGE_MISSING_MS`). */
262
+ private readonly missing;
263
+ private readonly listeners;
264
+ constructor(options?: RelayTransportOptions);
265
+ /** How reads go and how each relay is doing, for the connection panel. */
266
+ discovery(): DiscoveryStatus;
267
+ /** Back online on some network: relays that failed (or rate limited this address) on the old one are asked again. */
268
+ networkChanged(): void;
269
+ /** Called when a relay trips or recovers. */
270
+ subscribe(listener: (change?: DiscoveryChange) => void): () => void;
271
+ private changed;
272
+ /** What the relay did, for its breaker. */
273
+ private answered;
274
+ setRelays(relays: string[]): void;
275
+ describe(): {
276
+ protocol: string;
277
+ relays: string[];
278
+ };
279
+ /**
280
+ * Publishes to every relay. Peers may be configured with different relay
281
+ * sets; writing everywhere keeps the overlap warm, the DHT covers the rest.
282
+ * Returns once one relay took the packet: the others finish in the background.
283
+ */
284
+ publish(identity: Identity, records: GhostRecord[], options?: PkarrRequestOptions): Promise<void>;
285
+ /**
286
+ * The time the next packet under a key is dated: this clock's, and past every packet this client put or read there.
287
+ * BEP44 sequence numbers must strictly increase, and the clock that dated the last one may not be this one's.
288
+ */
289
+ nextTimestamp(pubKeyZ32: string): bigint;
290
+ /**
291
+ * Signs the records, dated by `nextTimestamp`, and hands the payload to `put` (the relays; the CLI adds the DHT).
292
+ * `put` calls `conflict` for a relay that answered 409: it holds a packet under this key dated at or after this one,
293
+ * which this client has not read (an inviter's warm packet under the key it gave its contact, from a clock ahead of
294
+ * this one). That packet is read from that relay, and the records go again dated just past it, once. Without this
295
+ * the packet was refused until this device's clock passed the other one's, however long that took, and on a relay
296
+ * that did take it, readers still preferred the later-dated empty packet of another relay.
297
+ */
298
+ publishDated(identity: Identity, records: GhostRecord[], put: (pubKeyZ32: string, payload: Uint8Array, timestamp: bigint, conflict: (relay: string) => void) => Promise<void>, options?: PkarrRequestOptions, again?: boolean): Promise<void>;
299
+ /** One relay's packet for a key, read now: its time, kept for `nextTimestamp`. Null when it has none or does not answer. */
300
+ private heldAt;
301
+ /** A packet under this key was read (on a relay, or by the CLI on the DHT): its time, for `nextTimestamp`. */
302
+ sawTimestamp(pubKeyZ32: string, timestamp: bigint): void;
303
+ /** Puts a payload signed elsewhere (a did:dht document), byte for byte, on every relay. `conflict`: as `publishDated` gives it. */
304
+ publishPayload(pubKeyZ32: string, payload: Uint8Array, options?: PkarrRequestOptions, conflict?: (relay: string) => void): Promise<void>;
305
+ /**
306
+ * Puts the packet on every relay and settles as soon as one of them took it. A relay that is slow to
307
+ * answer (one that stores the packet and answers the PUT only at the timeout) must not hold a link's
308
+ * presence, offer or answer back: the rest finish in the background, their outcomes still counted.
309
+ * When no relay takes it, this waits for all of them to say why.
310
+ */
311
+ private putEverywhere;
312
+ /**
313
+ * Public relays rate limit by IP (120 requests a minute at the time of
314
+ * writing) and several peers may share one address, so a poll costs one
315
+ * request: one relay is asked, the next one when this one fails, or when it
316
+ * has not answered within `HEDGE_MS` (a hedge: the first good answer wins and
317
+ * the other request is dropped). The newest validly signed packet seen so far
318
+ * wins, which also covers a relay that is still serving an older cached copy.
319
+ *
320
+ * In turn per key: a key's next read starts at the relay after the one that answered its last read. A relay that
321
+ * does not have a packet yet (a publish that reached only the other relay, one rate limited there) answers a key's
322
+ * reads at most once in a row. With one turn for all keys, a link that read its peer between two other reads landed
323
+ * on the same relay every time: a restarted member's offer, only on `pkarr.pubky.app`, went unread for 12 to 60 s
324
+ * while the member at the other end read `pkarr.pubky.org` (bug hunt r5a, 2026-09-29). A relay found slow lately
325
+ * (`SLOW_DEMOTE_MS`) goes after the others, whatever the turn.
326
+ *
327
+ * A hedge spends a second request, so it goes only where the budget has requests to spare (`hedgeRoom`), never for a
328
+ * background read (nobody waits on it), and later for a key whose last read found nothing (`HEDGE_MISSING_MS`).
329
+ */
330
+ resolve(pubKeyZ32: string, options?: PkarrRequestOptions): Promise<SignedPacket | null>;
331
+ /** The order a key's read asks the relays in: in turn per key (see `resolve`), relays found slow lately last. */
332
+ private readOrder;
333
+ /** One GET of a key at one relay, which `controller` drops. Never rejects: what happened is the outcome. */
334
+ private readFromRelay;
335
+ /**
336
+ * The relay was slow (`SLOW_MS`): it goes after the others for a while, and counts it against its breaker while
337
+ * another relay is there to ask. With none, a slow answer beats no answer: it counts as one.
338
+ */
339
+ private slow;
340
+ /**
341
+ * A hedge may go to this relay: its minute has more requests left than what groups leave a chat (`reserveOf`), so
342
+ * a second request for a read that already went out never takes one a pairing needs.
343
+ */
344
+ private hedgeRoom;
345
+ readAnsweredAt(pubKeyZ32: string): number | undefined;
346
+ /** The relays answered a read of this key now; answers older than `FRESH_READ_MS` are dropped as the list grows. */
347
+ private answeredRead;
348
+ /** The relay that answered a key's read, for its next one; the keys read longest ago go past `READ_TURNS_KEPT`. */
349
+ private readFrom;
350
+ /**
351
+ * A relay whose budget (this client's, or its own rate limit) held a packet back that another relay took: it gets
352
+ * that packet when it frees a request, as a background write. Only the newest per key and relay; a newer packet put
353
+ * everywhere drops it. Without this, that relay kept the key's older packet for good, and an app that restarted and
354
+ * read it first found a contact's offer long answered, answered it again, and waited on it (bug hunt r7a).
355
+ */
356
+ private catchUpLater;
357
+ private scheduleCatchUp;
358
+ private runCatchUp;
359
+ private put;
360
+ /**
361
+ * Discovery reads and writes share a bounded per-relay request budget; background requests only part of it, and
362
+ * groups leave a chat the budget refused its reserve. A link's write the budget refused goes before any read
363
+ * once a request is free again.
364
+ */
365
+ private take;
366
+ /**
367
+ * How long until this relay's budget takes this request, 0 when it would now: the oldest request of the minute over
368
+ * a limit ages out, a chat's reserve lapses, or a waiting write has had its turn. Keeps the lists to the minute, oldest first.
369
+ *
370
+ * Who goes first: a chat's refused write holds back everything but chat writes; a group's refused write holds back
371
+ * group reads and background requests, never a chat's. Background requests yield to a link that signals. A chat's
372
+ * signaling goes over the limit by its allowance (`SIGNALING_ALLOWANCE_SHARE`), and so do a few of its reads of a
373
+ * contact that just went away (`DEPARTED_READS`).
374
+ */
375
+ private heldFor;
376
+ /** A group's read of `key` asks: it waits for its turn from now on, unless it is taken (`readsAhead`). */
377
+ private readAsked;
378
+ /**
379
+ * Keys a group reads, still asking (within `WATCH_TURN_MS`), that were read longer ago than `key`: a share keeps a
380
+ * request for each. With `watchLane`, only watched keys the same other limits hold: one the groups' burst holds back
381
+ * would keep a turn it cannot take.
382
+ */
383
+ private readsAhead;
384
+ /** This contact's departed reads past the limit in the last minute (`DEPARTED_READS`). */
385
+ private departedReads;
386
+ /** One more, the contacts with none in the last minute dropped. */
387
+ private departedOverAdd;
388
+ private chatNeed;
389
+ /** How long groups still leave a chat its reserve on this relay (`CHAT_RESERVE`); a chat's need a minute old goes. */
390
+ private chatReservedFor;
391
+ /** Requests allowed to this relay a minute: this client's budget, or the relay's own share (`RELAY_REQUESTS_PER_MINUTE`). */
392
+ private limitOf;
393
+ /** What groups leave a chat on this relay: `CHAT_RESERVE`, or a third of a smaller budget. */
394
+ private reserveOf;
395
+ private isCoolingDown;
396
+ /** Left alone after failing at the network level. */
397
+ private networkCoolingDown;
398
+ /** How much longer the relay asked (429) to be left alone; 0 when it did not. */
399
+ private rateLimitedFor;
400
+ /** Leaves the relay alone for as long as its 429 asks; returns that, in ms. */
401
+ private coolDown;
402
+ /**
403
+ * One request under one time limit. `read` runs before the timer is cleared, so a body read there is bounded in
404
+ * time as well: a relay that sends its headers and then trickles, or never ends, is given up on like one that
405
+ * never answered.
406
+ */
407
+ /**
408
+ * The relay's own time, when its answer says it and this runtime may read it: Node and the Desktop can, a browser
409
+ * only when the relay exposes the header to other origins. Held against this device's clock (`ClockWatch`).
410
+ */
411
+ private serverTime;
412
+ onServerTime(listener: (time: ServerTime) => void): () => void;
413
+ /**
414
+ * The turn record's read (WISP 06 § Publishing and reading): every relay, in parallel, `TURN_SOURCE_TIMEOUT_MS`
415
+ * each. Unlike `resolve`, it does not stop at the first relay that answers, keeps nothing, and answers nothing from
416
+ * memory. Each request counts in the relay's minute, so chats see it, but is never held back by it: a device may
417
+ * not act before it has read its turn.
418
+ */
419
+ turnRead(pubKeyZ32: string, options?: {
420
+ timeoutMs?: number;
421
+ }): Promise<TurnSourceAnswer[]>;
422
+ /**
423
+ * The turn record's put: the bytes as given, to each relay `conditions` names, with `If-Match` on the sequence that
424
+ * relay is known to hold (none where it held no record). Unlike `putEverywhere`, a relay that refuses (409, 412,
425
+ * 428) is not asked again without the condition: its refusal is the answer, and every relay's answer is reported.
426
+ */
427
+ turnPut(pubKeyZ32: string, payload: Uint8Array, conditions: TurnConditions): Promise<TurnSourcePut[]>;
428
+ private turnRequest;
429
+ /** `cancel`: this client drops the request (a hedged read another relay answered first). */
430
+ private request;
431
+ }
432
+ /**
433
+ * A relay's answer body, at most RELAY_PAYLOAD_MAX_BYTES: refused on a larger `content-length` before anything is
434
+ * read, and otherwise streamed with a running count, so a relay (a default one or one the person added, working or
435
+ * compromised) cannot fill memory with a huge or endless body. Stops when `signal` aborts.
436
+ */
437
+ export declare function readRelayBody(response: Response, signal: AbortSignal, max?: number): Promise<Uint8Array>;
@@ -0,0 +1,99 @@
1
+ /**
2
+ * A circuit breaker per Pkarr relay. A relay that failed `threshold` times in a row (no answer, a server error,
3
+ * its own rate limit, 429, or an answer too slow to use, `SLOW_MS` in relay.ts) is left alone for a while: a minute the first time, twice as long each time it
4
+ * trips again, five minutes at most. When the wait is over, one request goes to it (the probe); an answer
5
+ * closes the breaker, a failure opens it again for longer. The relays still closed take its turns meanwhile.
6
+ *
7
+ * Only what the relay did counts: a request this client held back for its own budget is not a failure, and an
8
+ * answer the protocol expects (404, 409, 412, 428) is a relay working as it should.
9
+ */
10
+ /** Failures in a row that trip a relay's breaker. */
11
+ export declare const BREAKER_THRESHOLD = 3;
12
+ /** How long a relay is left alone the first time its breaker trips; doubled on each trip in a row. */
13
+ export declare const BREAKER_BASE_MS = 60000;
14
+ /** The longest a relay is left alone. */
15
+ export declare const BREAKER_MAX_MS: number;
16
+ /**
17
+ * While every relay is left alone for failing, one of them is asked this often anyway: with nothing else to try, a
18
+ * long wait only delays noticing that they answer again (a link stayed down minutes after the relays came back).
19
+ */
20
+ export declare const BREAKER_ALL_DOWN_PROBE_MS = 15000;
21
+ /** Why a request to a relay failed: its rate limit (`throttled`), or anything else (`error`). */
22
+ export type RelayFailure = "throttled" | "error";
23
+ /** A relay as the connection panel shows it: `ok`, `throttled` (its rate limit) or `failing`, until when. */
24
+ export interface RelayHealth {
25
+ relay: string;
26
+ state: "ok" | "throttled" | "failing";
27
+ /** When the relay is asked again (ms since the epoch), while it is left alone. */
28
+ until?: number;
29
+ /** What went wrong last, in a few words; never a key. */
30
+ reason?: string;
31
+ }
32
+ /**
33
+ * How this client reaches Pkarr right now, for the connection panel: the path its last read took ("dht", or
34
+ * the relay that answered), and the health of each relay it uses (none where it reads the DHT alone).
35
+ */
36
+ export interface DiscoveryStatus {
37
+ path: {
38
+ via: "dht";
39
+ } | {
40
+ via: "relay";
41
+ relay: string;
42
+ } | null;
43
+ relays: RelayHealth[];
44
+ }
45
+ export interface RelayBreakerOptions {
46
+ threshold?: number;
47
+ baseMs?: number;
48
+ maxMs?: number;
49
+ /** `BREAKER_ALL_DOWN_PROBE_MS`. */
50
+ allDownProbeMs?: number;
51
+ now?: () => number;
52
+ /** Told each time a relay trips: which, why, and for how long. */
53
+ onTrip?: (relay: string, reason: string, forMs: number) => void;
54
+ /** Told when a tripped relay answered its probe. */
55
+ onRecover?: (relay: string) => void;
56
+ }
57
+ export declare class RelayBreaker {
58
+ private readonly options;
59
+ private readonly circuits;
60
+ private readonly threshold;
61
+ private readonly baseMs;
62
+ private readonly maxMs;
63
+ private readonly allDownProbeMs;
64
+ private readonly now;
65
+ /** When a relay was last asked because every relay was left alone. */
66
+ private lastAllDownProbe;
67
+ constructor(options?: RelayBreakerOptions);
68
+ private circuit;
69
+ /** How long the relay is still left alone, in ms; 0 when a request may go (closed, or its probe is due). */
70
+ blockedFor(relay: string): number;
71
+ /** Why the relay is left alone, while it is: its rate limit or failures. */
72
+ blockedKind(relay: string): RelayFailure | undefined;
73
+ /** A request is going to the relay now: its probe, when the wait is over. Call only when `blockedFor` is 0. */
74
+ begin(relay: string): void;
75
+ /**
76
+ * When every relay of `relays` is left alone for failing (none for its rate limit, none with its probe due or out),
77
+ * the one whose wait ends first may be asked now, once every `BREAKER_ALL_DOWN_PROBE_MS`. Returns it, or null. The
78
+ * caller marks the request with `beginAllDown` when it really goes (a request its budget holds back is no probe).
79
+ */
80
+ allDownProbe(relays: string[]): string | null;
81
+ /** The probe `allDownProbe` named is going now: its answer closes the breaker, a failure trips it again. */
82
+ beginAllDown(relay: string): void;
83
+ /**
84
+ * A request that went to the relay was dropped before it answered, by this client (another relay answered first), or
85
+ * its answer says nothing either way: a probe among them is no longer out, and the next request may probe again.
86
+ */
87
+ cancel(relay: string): void;
88
+ /** The relay answered: whatever was wrong is over. */
89
+ success(relay: string): void;
90
+ /** The relay failed a request; a probe that fails trips it again at once. */
91
+ failure(relay: string, kind: RelayFailure, reason: string): void;
92
+ private trip;
93
+ /** How long until a relay left alone is asked again: its wait, or the next probe while every relay of `relays` is left alone. */
94
+ askedAgainIn(relay: string, relays: string[]): number;
95
+ /** A new network: every relay starts fresh. */
96
+ reset(): void;
97
+ /** Each relay's health, in the order given. */
98
+ health(relays: string[]): RelayHealth[];
99
+ }