@ensnode/ensnode-sdk 0.35.0 → 0.36.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/index.d.ts CHANGED
@@ -1,10 +1,8 @@
1
1
  import { Hex, Address, ByteArray } from 'viem';
2
- import * as _ensdomains_address_encoder from '@ensdomains/address-encoder';
3
2
  import { CoinType, EvmCoinType } from '@ensdomains/address-encoder';
4
3
  export { CoinType, EvmCoinType } from '@ensdomains/address-encoder';
5
4
  import { ENSNamespaceId } from '@ensnode/datasources';
6
- export { ENSNamespaceId, ENSNamespaceIds } from '@ensnode/datasources';
7
- import z from 'zod/v4';
5
+ export { ENSNamespaceId, ENSNamespaceIds, getENSRootChainId } from '@ensnode/datasources';
8
6
 
9
7
  /**
10
8
  * A hash value that uniquely identifies a single ENS name.
@@ -14,47 +12,249 @@ import z from 'zod/v4';
14
12
  * ```
15
13
  * namehash("vitalik.eth") === "0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835"
16
14
  * ```
17
- * @link https://docs.ens.domains/ensip/1#namehash-algorithm
15
+ * @see https://docs.ens.domains/ensip/1#namehash-algorithm
16
+ * @see https://ensnode.io/docs/reference/terminology#name-node-namehash
18
17
  */
19
18
  type Node = Hex;
20
19
  /**
21
- * A Name represents a human-readable ENS name.
20
+ * An ENS Name that may or may not be normalized.
22
21
  *
23
- * ex: vitalik.eth
22
+ * @example vitalik.eth
23
+ * @see https://ensnode.io/docs/reference/terminology#name-node-namehash
24
+ * @see https://docs.ens.domains/ensip/15
24
25
  */
25
26
  type Name = string;
27
+ /**
28
+ * A Normalized Name is an ENS Name that is guaranteed to be normalized.
29
+ *
30
+ * @example vitalik.eth
31
+ * @see https://ensnode.io/docs/reference/terminology#name-node-namehash
32
+ * @see https://docs.ens.domains/ensip/15
33
+ * @dev nominally typed to enforce usage & enhance codebase clarity
34
+ */
35
+ type NormalizedName = Name & {
36
+ __brand: "NormalizedName";
37
+ };
26
38
  /**
27
39
  * A LabelHash is the result of the labelhash function (which is just keccak256) on a Label.
28
40
  *
29
- * @link https://docs.ens.domains/terminology#labelhash
41
+ * @example
42
+ * ```
43
+ * labelhash('vitalik') === '0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc'
44
+ * ```
45
+ *
46
+ * @see https://docs.ens.domains/terminology#labelhash
47
+ * @see https://ensnode.io/docs/reference/terminology#labels-labelhashes-labelhash-function
30
48
  */
31
49
  type LabelHash = Hex;
32
50
  /**
33
51
  * A Label is a single part of an ENS Name.
34
52
  *
35
- * @link https://docs.ens.domains/terminology#label
53
+ * @example vitalik
54
+ *
55
+ * @see https://docs.ens.domains/terminology#label
56
+ * @see https://ensnode.io/docs/reference/terminology#labels-labelhashes-labelhash-function
36
57
  */
37
58
  type Label = string;
38
59
  /**
39
- * An EncodedLabelHash is a specially formatted unnormalized Label that should be interpreted as a
40
- * LabelHash literal, particularly for use within an ENS Name.
60
+ * An EncodedLabelHash is a specially formatted (unnormalized) Label formatted
61
+ * as a non-0x prefixed 32-byte hex string enclosed in square brackets.
62
+ *
63
+ * Care should be taken to distinguish Label values formatted as an
64
+ * EncodedLabelHash as either a LiteralLabel or an InterpretedLabel:
65
+ * - If a LiteralLabel is formatted as an EncodedLabelHash it does NOT
66
+ * symbolically represent the encoding of a LabelHash literal.
67
+ * - If an InterpretedLabel is formatted as an EncodedLabelHash it should be
68
+ * interpreted as encoding a LabelHash literal.
69
+ *
70
+ * An InterpretedLabel may be formatted as an EncodedLabelHash if the related
71
+ * LiteralLabel is:
72
+ * - not a normalized label
73
+ * - is an unknown value that could not be healed.
74
+ * - is too long for DNS-Encoding in contexts where DNS-Encoding was required.
75
+ *
76
+ * @example [af2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc]
41
77
  *
42
- * @example [abcd]
43
- * @example [abcd].example.eth
78
+ * @see https://ensnode.io/docs/reference/terminology#encoded-labelhash
44
79
  */
45
80
  type EncodedLabelHash = `[${string}]`;
46
-
47
- declare const ROOT_NODE: Node;
48
- declare const ETH_NODE: `0x${string}`;
49
- declare const BASENAMES_NODE: `0x${string}`;
50
- declare const LINEANAMES_NODE: `0x${string}`;
51
81
  /**
52
- * A set of nodes whose children are used for reverse resolution.
82
+ * A Literal Label is a Label as it literally appears onchain, without any interpretation
83
+ * or normalization processing. It may be an unnormalized label for reasons including:
84
+ * - being an empty label,
85
+ * - containing '.' characters,
86
+ * - being formatted as an EncodedLabelHash (which are not normalizable). Note that
87
+ * when LiteralLabel are formatted as an EncodedLabelHash they do NOT symbolically
88
+ * represent the encoding of a LabelHash literal, or
89
+ * - containing other unnormalized characters such as null bytes or other characters
90
+ * not suitable for display.
53
91
  *
54
- * Useful for identifying if a domain is used for reverse resolution.
55
- * See apps/ensindexer/src/handlers/Registry.ts for context.
92
+ *
93
+ * @see https://ensnode.io/docs/reference/terminology#literal-label
94
+ * @dev nominally typed to enforce usage & enhance codebase clarity
95
+ */
96
+ type LiteralLabel = Label & {
97
+ __brand: "LiteralLabel";
98
+ };
99
+ /**
100
+ * An Interpreted Label is a Label that is either:
101
+ * a) a Normalized Label, or
102
+ * b) an Unnormalizable Label exclusively for the reason that it is formatted
103
+ * as an Encoded LabelHash that should be interpreted as encoding a
104
+ * LabelHash literal, where the encoded LabelHash literal is the `labelhash`
105
+ * of the related LiteralLabel.
106
+ *
107
+ * @see https://ensnode.io/docs/reference/terminology#interpreted-label
108
+ * @dev nominally typed to enforce usage & enhance codebase clarity
56
109
  */
57
- declare const REVERSE_ROOT_NODES: Set<Node>;
110
+ type InterpretedLabel = Label & {
111
+ __brand: "InterpretedLabel";
112
+ };
113
+ /**
114
+ * A Literal Name is a Name as it literally appears onchain, composed of 0 or more Literal Labels
115
+ * joined by dots. It may be an unnormalized name for reasons including:
116
+ * - containing empty labels,
117
+ * - containing LiteralLabel values formatted as an EncodedLabelHash (which are
118
+ * not normalizable)). Note that when LiteralLabel values are formatted as an
119
+ * EncodedLabelHash they do NOT symbolically represent the encoding of a
120
+ * LabelHash literal, or
121
+ * - containing other unnormalized characters such as null bytes or other characters
122
+ * not suitable for display.
123
+ *
124
+ * @see https://ensnode.io/docs/reference/terminology#literal-name
125
+ * @dev nominally typed to enforce usage & enhance codebase clarity
126
+ */
127
+ type LiteralName = Name & {
128
+ __brand: "LiteralName";
129
+ };
130
+ /**
131
+ * An Interpreted Name is a Name that is entirely composed of 0 or more Interpreted Labels.
132
+ *
133
+ * That is, it is either:
134
+ * a) a Normalized Name, or
135
+ * b) an Unnormalizable Name exclusively for the reason that it contains 1 or
136
+ * more labels formatted as Encoded LabelHashes that should be interpreted
137
+ * as encoding a LabelHash literal, where the encoded LabelHash literal is
138
+ * the `labelhash` of the related LiteralLabel.
139
+ *
140
+ * @see https://ensnode.io/docs/reference/terminology#interpreted-name
141
+ * @dev nominally typed to enforce usage & enhance codebase clarity
142
+ */
143
+ type InterpretedName = Name & {
144
+ __brand: "InterpretedName";
145
+ };
146
+ /**
147
+ * A Subgraph Interpreted Label is a Literal Label that is either:
148
+ * a) (if subgraph-indexable): a Literal Label, of unknown normalization status, guaranteed to not
149
+ * contain any of the subgraph-unindexable UTF-8 characters (and therefore guaranteed not to be
150
+ * an Encoded LabelHash), or
151
+ * b) (if subgraph-unindexable): an Encoded LabelHash.
152
+ *
153
+ * @see https://ensnode.io/docs/reference/terminology#subgraph-interpreted-label
154
+ * @dev nominally typed to enforce usage & enhance codebase clarity
155
+ */
156
+ type SubgraphInterpretedLabel = Label & {
157
+ __brand: "SubgraphInterpretedLabel";
158
+ };
159
+ /**
160
+ * A Subgraph Interpreted Name is a name exclusively composed of 0 or more Subgraph Interpreted Labels.
161
+ *
162
+ * @see https://ensnode.io/docs/reference/terminology#subgraph-interpreted-name
163
+ * @dev nominally typed to enforce usage & enhance codebase clarity
164
+ */
165
+ type SubgraphInterpretedName = Name & {
166
+ __brand: "SubgraphInterpretedName";
167
+ };
168
+ /**
169
+ * A DNS-Encoded Name as a hex string, representing the binary DNS wire format encoding
170
+ * of a domain name. Used in ENS contracts for efficient name storage and transmission.
171
+ * Each label is prefixed with a length byte, and the entire sequence is null-terminated.
172
+ *
173
+ * @example "0x076578616d706c650365746800" represents "example.eth"
174
+ *
175
+ * @see https://docs.ens.domains/resolution/names/#dns-encoding
176
+ * @see https://github.com/ensdomains/ens-contracts/blob/staging/contracts/utils/NameCoder.sol
177
+ *
178
+ * DNS Packet Format for Domain Names:
179
+ * - Domain names are encoded as a sequence of 0 or more labels
180
+ * - Each label begins with a length byte (1 byte) indicating how many bytes follow for that label
181
+ * Note how this constrains each label in DNS encoded names to a max byte length of 255 bytes.
182
+ * - The bytes after the length byte represent the label, as a UTF-8 byte array
183
+ * - Labels are concatenated with no separators
184
+ * - The sequence ends with a null byte (0x00)
185
+ *
186
+ * Example: "example.eth" is encoded as:
187
+ * [0x07, 'e', 'x', 'a', 'm', 'p', 'l', 'e', 0x03, 'e', 't', 'h', 0x00]
188
+ * Where 0x07 is the length of "example", 0x03 is the length of "eth", and 0x00 marks the end
189
+ *
190
+ * Example: "" (empty string, i.e. root node) is encoded as:
191
+ * [0x00]
192
+ *
193
+ * Example: "👩🏼‍❤‍💋‍👨🏼.eth" (multi-byte unicode character) is encoded as:
194
+ * [0x20, 240, 159, 145, 169, 240, 159, 143, 188, 226, 128, 141, 226, 157, 164, 226,
195
+ * 128, 141, 240, 159, 146, 139, 226, 128, 141, 240, 159, 145, 168, 240, 159, 143,
196
+ * 188, 3, 'e', 't', 'h', 0x00]
197
+ *
198
+ * A DNS-Encoded Name Packet may be malformed if it does not exactly follow that specification.
199
+ * Possible reasons a DNS-Encoded Name may be malfomed include:
200
+ * - 'empty' packet
201
+ * - e.g. []
202
+ * ^-- that's empty!
203
+ * - 'length' byte overflowing packet byte length
204
+ * - e.g. [0x06, 'e', 't', 'h', 0x00]
205
+ * ^-- length overflows available bytes!
206
+ * - 'junk' at the end of the dns-encoded
207
+ * - e.g. [0x03, 'e', 't', 'h', 0x00, 0x01]
208
+ * ^-- junk!
209
+ *
210
+ * @dev This type is _structurally_ typed to aid Event Argument Typing — consumers should further
211
+ * cast the type of the event argument to a _nominally_ typed DNSEncodedName like {@link DNSEncodedLiteralName}
212
+ * or {@link DNSEncodedPartiallyInterpretedName} depending on the context.
213
+ */
214
+ type DNSEncodedName = Hex;
215
+ /**
216
+ * A DNSEncodedName that encodes a name containing 0 or more {@link LiteralLabel}s.
217
+ *
218
+ * In a DNSEncodedLiteralName, all labels are Literal Labels, including any Encoded-LabelHash-looking
219
+ * labels. Any Encoded-LabelHash-looking Literal Label values, when interpreted, will be formatted as
220
+ * the `labelhash` of the Literal Label value.
221
+ *
222
+ * The NameWrapper contract emits DNSEncodedLiteralNames:
223
+ * @see https://github.com/ensdomains/ens-contracts/blob/staging/contracts/utils/BytesUtils_LEGACY.sol
224
+ *
225
+ * The ThreeDNSToken contract emits DNSEncodedLiteralNames:
226
+ * @see https://github.com/3dns-xyz/contracts/blob/44937318ae26cc036982e8c6a496cd82ebdc2b12/src/regcontrol/libraries/BytesUtils.sol
227
+ *
228
+ * @dev nominally typed to enforce usage & enhance codebase clarity
229
+ */
230
+ type DNSEncodedLiteralName = DNSEncodedName & {
231
+ __brand: "DNSEncodedLiteralName";
232
+ };
233
+ /**
234
+ * A DNSEncodedName that encodes a name consisting of 0 or more labels that are either:
235
+ * a) Literal Labels, or
236
+ * b) Encoded LabelHashes, which are already an Interpreted Label.
237
+ *
238
+ * In a DNSEncodedPartiallyInterpretedName, any Encoded-LabelHash-looking decoded Labels (i.e. ones
239
+ * that match the regex /^\[[\da-f]{64}\]$/) represent an Encoded LabelHash. When decoding a
240
+ * DNSEncodedPartiallyInterpretedName, these labels are already considered Interpreted.
241
+ *
242
+ * NOTE: This type is unused in ENSv1, but its usage is anticipated in ENSv2 due to Encoded
243
+ * LabelHash support in the ENSv2 implementation of the NameCoder contract.
244
+ *
245
+ * @see https://github.com/ensdomains/ens-contracts/blob/staging/contracts/utils/NameCoder.sol
246
+ *
247
+ * @dev nominally typed to enforce usage & enhance codebase clarity
248
+ */
249
+ type DNSEncodedPartiallyInterpretedName = DNSEncodedName & {
250
+ __brand: "DNSEncodedPartiallyInterpretedName";
251
+ };
252
+
253
+ declare const ROOT_NODE: Node;
254
+ declare const ETH_NODE: Node;
255
+ declare const BASENAMES_NODE: Node;
256
+ declare const LINEANAMES_NODE: Node;
257
+ declare const ADDR_REVERSE_NODE: Node;
58
258
 
59
259
  /**
60
260
  * Implements one step of the namehash algorithm, combining `labelHash` with `node` to produce
@@ -62,20 +262,6 @@ declare const REVERSE_ROOT_NODES: Set<Node>;
62
262
  * the actual concatenation) in order to improve readability (i.e. read as [labelHash].[node]).
63
263
  */
64
264
  declare const makeSubdomainNode: (labelHash: LabelHash, node: Node) => Node;
65
- /**
66
- * Attempt to heal the labelHash of an addr.reverse subname using an address that might be related to the subname.
67
- *
68
- * @throws if maybeReverseAddress is not a valid Address
69
- * @throws if labelHash is not a valid Labelhash
70
- *
71
- * @returns the original label if healed, otherwise null
72
- */
73
- declare const maybeHealLabelByReverseAddress: ({ maybeReverseAddress, labelHash, }: {
74
- /** The address that is possibly associated with the addr.reverse subname */
75
- maybeReverseAddress: Address;
76
- /** The labelhash of the addr.reverse subname */
77
- labelHash: LabelHash;
78
- }) => string | null;
79
265
  /**
80
266
  * Encodes a uint256 bigint as hex string sized to 32 bytes.
81
267
  * Uses include, in the context of ENS, decoding the uint256-encoded tokenId of NFT-issuing contracts
@@ -83,18 +269,14 @@ declare const maybeHealLabelByReverseAddress: ({ maybeReverseAddress, labelHash,
83
269
  * (see NameWrapper, ETHRegistrarController)
84
270
  */
85
271
  declare const uint256ToHex32: (num: bigint) => Hex;
272
+
86
273
  /**
87
- * Check if any characters in `label` are "unindexable".
88
- *
89
- * Related logic in ENS Subgraph:
90
- * https://github.com/ensdomains/ens-subgraph/blob/c844791/src/utils.ts#L68
91
- *
92
- * @param label - The label to check. Note:
93
- * A `null` value for `label` represents an unhealable labelhash.
274
+ * Converts an EVM address to its lowercase representation.
94
275
  *
95
- * @returns `true` if the label is indexable, `false` otherwise.
276
+ * @param address - EVM address to convert.
277
+ * @returns The lowercase representation of the EVM address.
96
278
  */
97
- declare const isLabelIndexable: (label: Label | null) => label is Label;
279
+ declare function asLowerCaseAddress(address: Address): Address;
98
280
 
99
281
  /**
100
282
  * Cache that maps from string -> ValueType.
@@ -163,6 +345,17 @@ declare const uniq: <T>(arr: T[]) => T[];
163
345
  * Guaranteed to be a positive integer.
164
346
  **/
165
347
  type ChainId = number;
348
+ /**
349
+ * Defaultable Chain ID
350
+ *
351
+ * Represents a unique identifier for a chain, or
352
+ * the default chain as defined by ENSIP-19.
353
+ *
354
+ * @see https://docs.ens.domains/ensip/19/#annex-supported-chains
355
+ *
356
+ * Guaranteed to be a non-negative integer.
357
+ **/
358
+ type DefaultableChainId = typeof DEFAULT_EVM_CHAIN_ID | ChainId;
166
359
  /**
167
360
  * Represents an account (contract or EOA) at `address` on chain `chainId`.
168
361
  *
@@ -185,7 +378,11 @@ type Datetime = Date;
185
378
  /**
186
379
  * Unix timestamp value
187
380
  *
188
- * Guaranteed to be an integer.
381
+ * Represents the number of seconds that have elapsed
382
+ * since January 1, 1970 (midnight UTC/GMT).
383
+ *
384
+ * Guaranteed to be an integer. May be zero or negative to represent a time at or
385
+ * before Jan 1, 1970.
189
386
  */
190
387
  type UnixTimestamp = number;
191
388
  /**
@@ -260,7 +457,7 @@ type DeepPartial<T> = {
260
457
  };
261
458
 
262
459
  /**
263
- * A string representation of {@link ChainId}.
460
+ * Serialized representation of {@link ChainId}.
264
461
  **/
265
462
  type ChainIdString = string;
266
463
  /**
@@ -270,7 +467,7 @@ type ChainIdString = string;
270
467
  */
271
468
  type DatetimeISO8601 = string;
272
469
  /**
273
- * A string representation of a {@link URL}.
470
+ * Serialized representation of a {@link URL}.
274
471
  */
275
472
  type UrlString = string;
276
473
 
@@ -289,6 +486,7 @@ declare function serializeUrl(url: URL): UrlString;
289
486
 
290
487
  declare function deserializeChainId(maybeChainId: ChainIdString, valueLabel?: string): ChainId;
291
488
  declare function deserializeDatetime(maybeDatetime: string, valueLabel?: string): Datetime;
489
+ declare function deserializeUnixTimestamp(maybeTimestamp: number, valueLabel?: string): number;
292
490
  declare function deserializeUrl(maybeUrl: UrlString, valueLabel?: string): URL;
293
491
  declare function deserializeBlockNumber(maybeBlockNumber: number, valueLabel?: string): BlockNumber;
294
492
  declare function deserializeBlockrange(maybeBlockrange: Partial<Blockrange>, valueLabel?: string): {
@@ -304,7 +502,7 @@ declare function deserializeDuration(maybeDuration: string, valueLabel?: string)
304
502
  * @param name - The Name to check for normalization
305
503
  * @returns True if the name is normalized according to ENS normalization rules, false otherwise
306
504
  */
307
- declare function isNormalizedName(name: Name): boolean;
505
+ declare function isNormalizedName(name: Name): name is NormalizedName;
308
506
  /**
309
507
  * Determines whether the Label is normalized.
310
508
  *
@@ -319,30 +517,60 @@ declare function isNormalizedLabel(label: Label): boolean;
319
517
  declare const accountIdEqual: (a: AccountId, b: AccountId) => boolean;
320
518
 
321
519
  /**
322
- * Transforms a Literal Label into an Interpreted Label.
520
+ * Interprets a Literal Label, producing an Interpreted Label.
323
521
  *
324
522
  * @see https://ensnode.io/docs/reference/terminology#literal-label
325
523
  * @see https://ensnode.io/docs/reference/terminology#interpreted-label
326
524
  *
327
525
  * @param label - The Literal Label string to interpret
328
- * @returns The provided label if it is normalized, else the EncodedLabelHash of the label
526
+ * @returns The provided label if it is a normalized label, else the EncodedLabelHash of the label
329
527
  */
330
- declare function interpretLiteralLabel(label: Label): Label | EncodedLabelHash;
528
+ declare function literalLabelToInterpretedLabel(label: LiteralLabel): InterpretedLabel;
331
529
  /**
332
- * Transforms a Literal Name into an Interpreted Name.
530
+ * Interprets an ordered list of Literal Labels, producing an Interpreted Name.
333
531
  *
334
- * @see https://ensnode.io/docs/reference/terminology#literal-name
335
- * @see https://ensnode.io/docs/reference/terminology#interpreted-name
532
+ * Note that it's important that the Literal Labels are provided as an array, otherwise it's
533
+ * impossible to differentiate between 'a.label.eth' being ['a.label', 'eth'] or ['a', 'label', 'eth'].
534
+ *
535
+ * Note that the input is an ordered list of _Literal_ Labels: in this context, any literal label
536
+ * that is formatted as an Encoded LabelHash will NOT be interpreted as such. Instead it will be
537
+ * interpreted into an Encoded LabelHash that encodes the literal labelhash of the Literal Label.
336
538
  *
337
- * If the name provided to this function contains empty-string labels (i.e 'this..name'),
338
- * then the empty string labels will be Interpreted. Empty-string is not a normalizable name, so the
339
- * label will be replaced with its Encoded LabelHash representation (i.e. )
539
+ * @param labels An ordered list of 0 or more Literal Labels
540
+ * @returns An InterpretedName
541
+ */
542
+ declare function literalLabelsToInterpretedName(labels: LiteralLabel[]): InterpretedName;
543
+ /**
544
+ * Joins the list of Interpreted Labels with '.' to form an Interpreted Name.
545
+ *
546
+ * @param labels An ordered list of 0 or more Interpreted Labels
547
+ * @returns An InterpretedName
548
+ */
549
+ declare function interpretedLabelsToInterpretedName(labels: InterpretedLabel[]): InterpretedName;
550
+ /**
551
+ * Joins the list of Literal Labels with '.' to form a Literal Name.
552
+ *
553
+ * Note: LiteralLabel values may contain '.' characters, which will be preserved
554
+ * in the resulting LiteralName. Therefore, the number of labels in the returned
555
+ * LiteralName may be greater than the number of LiteralLabels in the input array.
556
+ *
557
+ * @param labels An ordered list of 0 or more Literal Labels
558
+ * @returns An LiteralName
559
+ */
560
+ declare function literalLabelsToLiteralName(labels: LiteralLabel[]): LiteralName;
561
+
562
+ /**
563
+ * Implements the ENS `labelhash` function for Literal Labels.
564
+ * @see https://docs.ens.domains/ensip/1
340
565
  *
341
- * @param name - The Literal Name string to interpret
342
- * @returns The provided name if it is normalized, else converts each label in name that is not a
343
- * normalized label into an Interpreted Label
566
+ * @param label the Literal Label to hash
567
+ * @returns the hash of the provided label
568
+ * @dev This function is viem/ens#labelhash but without the special-case handling of Encoded LabelHashes.
344
569
  */
345
- declare function interpretLiteralName(name: Name): Name;
570
+ declare const labelhashLiteralLabel: (label: LiteralLabel) => LabelHash;
571
+
572
+ declare function isHttpProtocol(url: URL): boolean;
573
+ declare function isWebSocketProtocol(url: URL): boolean;
346
574
 
347
575
  /**
348
576
  * The ETH coinType.
@@ -356,7 +584,7 @@ declare const ETH_COIN_TYPE: CoinType;
356
584
  *
357
585
  * @see https://docs.ens.domains/ensip/19
358
586
  */
359
- declare const DEFAULT_EVM_CHAIN_ID: ChainId;
587
+ declare const DEFAULT_EVM_CHAIN_ID = 0;
360
588
  /**
361
589
  * ENSIP-19 EVM CoinType representing the 'default' coinType for EVM chains in ENS.
362
590
  *
@@ -390,17 +618,49 @@ declare const evmChainIdToCoinType: (chainId: ChainId) => CoinType;
390
618
  declare const bigintToCoinType: (value: bigint) => CoinType;
391
619
 
392
620
  /**
393
- * Constructs a name hierarchy from a given Name.
394
- * i.e. sub.example.eth -> [sub.example.eth, example.eth, eth]
621
+ * Constructs a name hierarchy from a given NormalizedName.
622
+ *
623
+ * @example
624
+ * ```
625
+ * getNameHierarchy("sub.example.eth") -> ["sub.example.eth", "example.eth", "eth"]
626
+ * ```
627
+ *
628
+ * @dev by restricting the input type to NormalizedName we guarantee that we can split and join
629
+ * on '.' and receive NormalizedNames as a result
395
630
  */
396
- declare const getNameHierarchy: (name: Name) => Name[];
631
+ declare const getNameHierarchy: (name: NormalizedName) => NormalizedName[];
632
+ /**
633
+ * Beautifies a name by converting each normalized label in the provided name to
634
+ * its "beautified" form. Labels that are not normalized retain their original value.
635
+ *
636
+ * Invariants:
637
+ * - The number of labels in the returned name is the same as the number of labels in the input name.
638
+ * - The order of the labels in the returned name is the same as the order of the labels in the input name.
639
+ * - If a label in the input is normalized, it is returned in its "beautified" form.
640
+ * - If a label in the input name is not normalized, it is returned without modification.
641
+ * - Therefore, the result of ens_normalize(beautifyName(name)) is the same as the result of ens_normalize(name).
642
+ *
643
+ * The "beautified form" of a normalized label converts special sequences of
644
+ * emojis and other special characters to their "beautified" equivalents. All
645
+ * such conversions transform X -> Y where Y is normalizable and normalizes back to X.
646
+ * Ex: '1⃣2⃣' (normalized) to '1️⃣2️⃣' (normalizable but not normalized).
647
+ * Ex: 'ξethereum' (normalized) to 'Ξethereum' (normalizable, but not normalized).
648
+ * Ex: 'abc' (normalized) to 'abc' (also normalized, no conversion).
649
+ * Ex: 'ABC' (normalizable but not normalized) to 'ABC' (no conversion).
650
+ * Ex: 'invalid|label' (not normalizable) to 'invalid|label' (no conversion).
651
+ * Ex: '' (unnormalized as a label) to '' (no conversion).
652
+ *
653
+ * @param name - The name to beautify.
654
+ * @returns The beautified name.
655
+ */
656
+ declare const beautifyName: (name: Name) => Name;
397
657
 
398
658
  /**
399
659
  * Gets the Label used for the reverse names of subnames as per ENSIP-11 & ENSIP-19.
400
660
  *
401
661
  * @see https://docs.ens.domains/ensip/19/#reverse-resolution
402
662
  */
403
- declare const addrReverseLabel: (address: Address) => Label;
663
+ declare const addrReverseLabel: (address: Address) => LiteralLabel;
404
664
  /**
405
665
  * Converts `coinType` to prefix-free hex string.
406
666
  *
@@ -439,11 +699,40 @@ declare function parseReverseName(name: Name): {
439
699
  *
440
700
  * @see https://ensnode.io/docs/reference/terminology#encoded-labelhash
441
701
  *
442
- * @param labelHash - A 32-byte hash string starting with '0x'
702
+ * @param labelHash - A 32-byte lowercase hash string starting with '0x'
443
703
  * @returns The encoded label hash in format `[hash_without_0x_prefix]`
444
704
  */
445
705
  declare const encodeLabelHash: (labelHash: LabelHash) => EncodedLabelHash;
446
706
 
707
+ /**
708
+ * Decodes a DNS-Encoded name consisting of Literal Labels into an ordered list of Literal Labels.
709
+ *
710
+ * For discussion on DNS-Encoding, see the {@link DNSEncodedName} and {@link DNSEncodedLiteralName} types.
711
+ *
712
+ * Due to the constraints of DNS-Encoding, there is an additional guarantee that each Literal Label
713
+ * in the resulting list is guaranteed to have a maximum byte length of 255.
714
+ *
715
+ * @param packet a hex string that encodes a DNSEncodedLiteralName
716
+ * @returns A list of the LiteralLabels contained in packet
717
+ * @throws If the packet is malformed
718
+ * @dev This is just `decodeDNSEncodedName` with semantic input/output
719
+ */
720
+ declare function decodeDNSEncodedLiteralName(packet: DNSEncodedLiteralName): LiteralLabel[];
721
+ /**
722
+ * Decodes a DNS-Encoded Name into an ordered list of string segments.
723
+ *
724
+ * For discussion on DNS-Encoding, see the {@link DNSEncodedName} type.
725
+ *
726
+ * Due to the constraints of DNS-Encoding, there is an additional guarantee that each segment
727
+ * in the resulting list is guaranteed to have a maximum byte length of 255.
728
+ *
729
+ * @param packet a hex string that encodes a DNSEncodedName
730
+ * @returns A UTF-8 string array of the segments contained in packet
731
+ * @throws If the packet is malformed
732
+ * @dev This is the generic implementation of DNS-Encoded Name Decoding
733
+ */
734
+ declare function decodeDNSEncodedName(packet: DNSEncodedName): string[];
735
+
447
736
  /**
448
737
  * A label set ID identifies a set of labels that can be used for deterministic healing.
449
738
  * A label set allows clients to deterministically heal their state against a server,
@@ -504,22 +793,56 @@ declare enum PluginName {
504
793
  Basenames = "basenames",
505
794
  Lineanames = "lineanames",
506
795
  ThreeDNS = "threedns",
507
- ReverseResolvers = "reverse-resolvers",
796
+ ProtocolAcceleration = "protocol-acceleration",
508
797
  Referrals = "referrals",
509
798
  TokenScope = "tokenscope"
510
799
  }
511
800
  /**
512
- * Information about ENSIndexer's dependencies.
801
+ * Version info about ENSIndexer and its dependencies.
513
802
  */
514
- interface DependencyInfo {
515
- /** Node.js runtime version */
803
+ interface ENSIndexerVersionInfo {
804
+ /**
805
+ * Node.js runtime version
806
+ *
807
+ * @see https://nodejs.org/en/about/previous-releases
808
+ **/
516
809
  nodejs: string;
517
- /** Ponder framework version */
810
+ /**
811
+ * Ponder framework version
812
+ *
813
+ * @see https://www.npmjs.com/package/ponder
814
+ **/
518
815
  ponder: string;
519
- /** ENSRainbow service version */
816
+ /**
817
+ * ENSDb service version
818
+ *
819
+ * Guaranteed to be the same as {@link ENSIndexerVersionInfo.ensIndexer}.
820
+ * */
821
+ ensDb: string;
822
+ /**
823
+ * ENSIndexer service version
824
+ *
825
+ * @see https://ghcr.io/namehash/ensnode/ensindexer
826
+ **/
827
+ ensIndexer: string;
828
+ /**
829
+ * ENSRainbow service version
830
+ *
831
+ * @see https://ghcr.io/namehash/ensnode/ensindexer
832
+ **/
520
833
  ensRainbow: string;
521
- /** ENSRainbow schema version */
834
+ /**
835
+ * ENSRainbow schema version
836
+ **/
522
837
  ensRainbowSchema: number;
838
+ /**
839
+ * ENS Normalize package version
840
+ *
841
+ * Available on NPM as: `@adraffy/ens-normalize`
842
+ *
843
+ * @see https://www.npmjs.com/package/@adraffy/ens-normalize
844
+ **/
845
+ ensNormalize: string;
523
846
  }
524
847
  /**
525
848
  * Complete public configuration object for ENSIndexer.
@@ -534,24 +857,6 @@ interface ENSIndexerPublicConfig {
534
857
  * See {@link ENSNamespaceIds} for available namespace identifiers.
535
858
  */
536
859
  namespace: ENSNamespaceId;
537
- /**
538
- * An ENSAdmin URL
539
- *
540
- * The ENSNode root api route `/` redirects to {@link ensAdminUrl},
541
- * configuring ENSAdmin with an entry for this instance of ENSNode,
542
- * identified by {@link ensNodePublicUrl}.
543
- *
544
- * @see https://ensnode.io/ensadmin/overview/what-is-ensadmin
545
- */
546
- ensAdminUrl: URL;
547
- /**
548
- * The publicly accessible endpoint of the ENSNode API
549
- * (ex: http://localhost:42069).
550
- *
551
- * ENSAdmin will use this url to connect to the ENSNode api for querying
552
- * state about the ENSNode instance.
553
- */
554
- ensNodePublicUrl: URL;
555
860
  /**
556
861
  * The "fully pinned" label set reference that ENSIndexer will request ENSRainbow use for deterministic label healing across time. This label set reference is "fully pinned" as it requires both the labelSetId and labelSetVersion fields to be defined.
557
862
  */
@@ -566,105 +871,79 @@ interface ENSIndexerPublicConfig {
566
871
  */
567
872
  databaseSchemaName: string;
568
873
  /**
569
- * A set of {@link PluginName}s indicating which plugins to activate.
874
+ * A set of strings referring to the names of plugins that are active.
875
+ *
876
+ * For future-proofing, this is a list of strings that may or may
877
+ * not be currently valid {@link PluginName} values.
570
878
  *
571
879
  * Invariants:
572
- * - A set of valid {@link PluginName}s with at least one value
880
+ * - A set of strings with at least one value.
573
881
  */
574
- plugins: PluginName[];
882
+ plugins: string[];
575
883
  /**
576
- * Enable or disable healing of addr.reverse subnames.
577
- * If this is set to true, ENSIndexer will attempt to heal subnames of
578
- * addr.reverse.
884
+ * Indexed Chain IDs
885
+ *
886
+ * Includes the {@link ChainId} for each chain being indexed.
579
887
  */
580
- healReverseAddresses: boolean;
888
+ indexedChainIds: Set<ChainId>;
581
889
  /**
582
- * Enable or disable the indexing of Resolver record values.
583
- * If this is set to false, ENSIndexer will apply subgraph-backwards
584
- * compatible logic that only tracks the keys of Resolver records.
585
- * If this is set to true, ENSIndexer will track both the keys and the values
586
- * of Resolver records.
890
+ * A feature flag to enable/disable ENSIndexer's Subgraph Compatible Indexing Behavior.
587
891
  *
588
- * WARNING: Special care must be taken when interacting with indexed resolver
589
- * record values. It is unsafe to naively assume that indexed resolver record
590
- * values are equivalent to the resolver record values that would be returned
591
- * through dynamic lookups via the ENS protocol. For example, if a resolver
592
- * implements CCIP-Read, the resolver records may not be discoverable through
593
- * onchain indexing. This feature is under R&D. At this time we do not
594
- * recommend anyone directly use indexed resolver record values in their
595
- * applications. Features are planned in the ENSNode roadmap that will
596
- * provide safe use of indexed resolver record values (in appropriate
597
- * contexts).
892
+ * If {@link isSubgraphCompatible} is true, indexing behavior will match that of the legacy ENS
893
+ * Subgraph.
598
894
  *
599
- * Note that enabling {@link indexAdditionalResolverRecords} results in indexed data becoming a
600
- * _superset_ of the Subgraph. For exact data-level backwards compatibility with the ENS Subgraph,
601
- * {@link indexAdditionalResolverRecords} should be `false`.
602
- */
603
- indexAdditionalResolverRecords: boolean;
604
- /**
605
- * Controls ENSIndexer's handling of Literal Labels and Literal Names
606
- * This configuration only applies to the Subgraph datamodel and Subgraph Compatible GraphQL API responses.
895
+ * ENSIndexer will store and return Literal Labels and Literal Names without further interpretation.
896
+ * @see https://ensnode.io/docs/reference/terminology#literal-label
897
+ * @see https://ensnode.io/docs/reference/terminology#literal-name
607
898
  *
608
- * When set to true, all Literal Labels and Literal Names encountered by ENSIndexer will be Interpreted.
609
- * - https://ensnode.io/docs/reference/terminology#interpreted-label
610
- * - https://ensnode.io/docs/reference/terminology#interpreted-name
899
+ * If {@link isSubgraphCompatible} is true, the following invariants are true for the ENSIndexerConfig:
900
+ * 1. only the 'subgraph' plugin is enabled, and
901
+ * 2. the labelSet must be { labelSetId: 'subgraph', labelSetVersion: 0 }
611
902
  *
612
- * That is,
613
- * 1) all Labels stored and returned by ENSIndexer will either be normalized or represented as an Encoded
614
- * LabelHash, and
615
- * 2) all Names stored and returned by ENSIndexer will either be normalized or consist of Labels that
616
- * may be represented as an Encoded LabelHash of the Literal Label value found onchain.
903
+ * If {@link isSubgraphCompatible} is false, ENSIndexer will additionally:
617
904
  *
618
- * When set to false, ENSIndexer will store and return Literal Labels and Literal Names without further
619
- * interpretation.
620
- * - https://ensnode.io/docs/reference/terminology#literal-label
621
- * - https://ensnode.io/docs/reference/terminology#literal-name
905
+ * 1. ENSIndexer will heal all subnames of addr.reverse on the ENS Root Chain.
622
906
  *
623
- * NOTE: {@link replaceUnnormalized} must be `false` for subgraph compatible indexing behavior.
624
- */
625
- replaceUnnormalized: boolean;
626
- /**
627
- * Indexed Chain IDs
907
+ * 2. ENSIndexer will track both the keys and the values of Resolver records.
628
908
  *
629
- * Includes the {@link ChainId} for each chain being indexed.
630
- */
631
- indexedChainIds: Set<ChainId>;
632
- /**
633
- * A flag derived from the built config indicating whether ENSIndexer is operating in a
634
- * subgraph-compatible way. This flag is true if:
635
- * a) only the subgraph plugin is activated,
636
- * b) healReverseAddresess is false, and
637
- * c) indexRecordValues is false
909
+ * WARNING: Special care must be taken when interacting with indexed resolver record values. It
910
+ * is unsafe to naively assume that indexed resolver record values are equivalent to the
911
+ * resolver record values that would be returned through dynamic lookups via the ENS protocol.
912
+ * For example, if a resolver implements CCIP-Read, the resolver records may not be
913
+ * discoverable through onchain indexing.
914
+ *
915
+ * 3. Literal Labels and Literal Names encountered by ENSIndexer will be Interpreted.
916
+ * @see https://ensnode.io/docs/reference/terminology#interpreted-label
917
+ * @see https://ensnode.io/docs/reference/terminology#interpreted-name
638
918
  *
639
- * If {@link isSubgraphCompatible} is true, ENSIndexer will:
640
- * 1) use subgraph-compatible IDs for entities and events
641
- * 2) limit indexing behavior to subgraph indexing semantics
919
+ * That is,
920
+ * a) all Labels stored and returned by ENSIndexer will be Interpreted Labels, which are either:
921
+ * i. normalized, or
922
+ * ii. represented as an Encoded LabelHash of the Literal Label value found onchain, and
923
+ * b) all Names stored and returned by ENSIndexer will be Interpreted Names, which are exclusively
924
+ * composed of Interpreted Labels.
642
925
  */
643
926
  isSubgraphCompatible: boolean;
644
927
  /**
645
- * Information about the ENSIndexer instance dependencies.
928
+ * Version info about ENSIndexer.
646
929
  */
647
- dependencyInfo: DependencyInfo;
930
+ versionInfo: ENSIndexerVersionInfo;
648
931
  }
649
932
 
650
933
  type SerializedIndexedChainIds = Array<ChainId>;
651
934
  /**
652
935
  * Serialized representation of {@link ENSIndexerPublicConfig}
653
936
  */
654
- interface SerializedENSIndexerPublicConfig extends Omit<ENSIndexerPublicConfig, "ensAdminUrl" | "ensNodePublicUrl" | "indexedChainIds"> {
655
- /**
656
- * String representation of {@link ENSIndexerPublicConfig.ensAdminUrl}.
657
- */
658
- ensAdminUrl: UrlString;
659
- /**
660
- * String representation of {@link ENSIndexerPublicConfig.ensNodePublicUrl}.
661
- */
662
- ensNodePublicUrl: UrlString;
937
+ interface SerializedENSIndexerPublicConfig extends Omit<ENSIndexerPublicConfig, "indexedChainIds"> {
663
938
  /**
664
939
  * Array representation of {@link ENSIndexerPublicConfig.indexedChainIds}.
665
940
  */
666
941
  indexedChainIds: ChainId[];
667
942
  }
943
+ /**
944
+ * Serialized representation of {@link ENSIndexerVersionInfo}
945
+ */
946
+ type SerializedENSIndexerVersionInfo = ENSIndexerVersionInfo;
668
947
 
669
948
  /**
670
949
  * Serialize a {@link ENSIndexerPublicConfig} object.
@@ -672,11 +951,12 @@ interface SerializedENSIndexerPublicConfig extends Omit<ENSIndexerPublicConfig,
672
951
  declare function deserializeENSIndexerPublicConfig(maybeConfig: SerializedENSIndexerPublicConfig, valueLabel?: string): ENSIndexerPublicConfig;
673
952
 
674
953
  /**
675
- * Determines if the provided `config` produces an index equivalent to the ENS Subgraph.
954
+ * Determines if the provided `config` results in indexing behavior compatible with the legacy ENS
955
+ * Subgraph.
676
956
  *
677
957
  * @see https://ensnode.io/docs/reference/subgraph-compatibility/
678
958
  */
679
- declare function isSubgraphCompatible(config: Pick<ENSIndexerPublicConfig, "plugins" | "healReverseAddresses" | "indexAdditionalResolverRecords" | "replaceUnnormalized" | "labelSet">): boolean;
959
+ declare function isSubgraphCompatible(config: Pick<ENSIndexerPublicConfig, "namespace" | "plugins" | "labelSet">): boolean;
680
960
 
681
961
  /**
682
962
  * Serializes a {@link ChainConfig} object.
@@ -687,114 +967,6 @@ declare function serializeIndexedChainIds(indexedChainIds: Set<ChainId>): Serial
687
967
  */
688
968
  declare function serializeENSIndexerPublicConfig(config: ENSIndexerPublicConfig): SerializedENSIndexerPublicConfig;
689
969
 
690
- /**
691
- * All zod schemas we define must remain internal implementation details.
692
- * We want the freedom to move away from zod in the future without impacting
693
- * any users of the ensnode-sdk package.
694
- *
695
- * The only way to share Zod schemas is to re-export them from
696
- * `./src/internal.ts` file.
697
- */
698
-
699
- /**
700
- * Zod `.check()` function input.
701
- */
702
- type ZodCheckFnInput<T> = z.core.ParsePayload<T>;
703
-
704
- /**
705
- * All zod schemas we define must remain internal implementation details.
706
- * We want the freedom to move away from zod in the future without impacting
707
- * any users of the ensnode-sdk package.
708
- *
709
- * The only way to share Zod schemas is to re-export them from
710
- * `./src/internal.ts` file.
711
- */
712
-
713
- /**
714
- * Makes a schema for parsing {@link IndexedChainIds}.
715
- */
716
- declare const makeIndexedChainIdsSchema: (valueLabel?: string) => z.ZodPipe<z.ZodArray<z.ZodInt>, z.ZodTransform<Set<number>, number[]>>;
717
- /**
718
- * Makes a schema for parsing a list of {@link PluginName} items.
719
- *
720
- * The list is guaranteed to include at least one item exists, and no duplicates.
721
- */
722
- declare const makePluginsListSchema: (valueLabel?: string) => z.ZodArray<z.ZodEnum<typeof PluginName>>;
723
- /**
724
- * Makes a schema for parsing a name for a database schema.
725
- *
726
- * The name is guaranteed to be a non-empty string.
727
- */
728
- declare const makeDatabaseSchemaNameSchema: (valueLabel?: string) => z.ZodString;
729
- /**
730
- * Makes a schema for parsing a label set ID.
731
- *
732
- * The label set ID is guaranteed to be a string between 1-50 characters
733
- * containing only lowercase letters (a-z) and hyphens (-).
734
- *
735
- * @param valueLabel - The label to use in error messages (e.g., "Label set ID", "LABEL_SET_ID")
736
- */
737
- declare const makeLabelSetIdSchema: (valueLabel: string) => z.ZodString;
738
- /**
739
- * Makes a schema for parsing a label set version.
740
- *
741
- * The label set version is guaranteed to be a non-negative integer.
742
- *
743
- * @param valueLabel - The label to use in error messages (e.g., "Label set version", "LABEL_SET_VERSION")
744
-
745
- */
746
- declare const makeLabelSetVersionSchema: (valueLabel: string) => z.ZodPipe<z.coerce.ZodCoercedNumber<unknown>, z.ZodInt>;
747
- /**
748
- * Makes a schema for parsing a label set where both label set ID and label set version are required.
749
- *
750
- * @param valueLabel - The label to use in error messages (e.g., "Label set", "LABEL_SET")
751
- */
752
- declare const makeFullyPinnedLabelSetSchema: (valueLabel?: string) => z.ZodObject<{
753
- labelSetId: z.ZodString;
754
- labelSetVersion: z.ZodPipe<z.coerce.ZodCoercedNumber<unknown>, z.ZodInt>;
755
- }, z.core.$strip>;
756
- declare const makeDependencyInfoSchema: (valueLabel?: string) => z.ZodObject<{
757
- nodejs: z.ZodString;
758
- ponder: z.ZodString;
759
- ensRainbow: z.ZodString;
760
- ensRainbowSchema: z.ZodInt;
761
- }, z.core.$strict>;
762
- declare function invariant_reverseResolversPluginNeedsResolverRecords(ctx: ZodCheckFnInput<Pick<ENSIndexerPublicConfig, "plugins" | "indexAdditionalResolverRecords">>): void;
763
- declare function invariant_isSubgraphCompatibleRequirements(ctx: ZodCheckFnInput<Pick<ENSIndexerPublicConfig, "plugins" | "isSubgraphCompatible" | "healReverseAddresses" | "indexAdditionalResolverRecords" | "replaceUnnormalized" | "labelSet">>): void;
764
- /**
765
- * ENSIndexer Public Config Schema
766
- *
767
- * Makes a Zod schema definition for validating all important settings used
768
- * during runtime of the ENSIndexer instance.
769
- */
770
- declare const makeENSIndexerPublicConfigSchema: (valueLabel?: string) => z.ZodObject<{
771
- ensAdminUrl: z.ZodPipe<z.ZodURL, z.ZodTransform<URL, string>>;
772
- ensNodePublicUrl: z.ZodPipe<z.ZodURL, z.ZodTransform<URL, string>>;
773
- labelSet: z.ZodObject<{
774
- labelSetId: z.ZodString;
775
- labelSetVersion: z.ZodPipe<z.coerce.ZodCoercedNumber<unknown>, z.ZodInt>;
776
- }, z.core.$strip>;
777
- healReverseAddresses: z.ZodBoolean;
778
- indexAdditionalResolverRecords: z.ZodBoolean;
779
- replaceUnnormalized: z.ZodBoolean;
780
- indexedChainIds: z.ZodPipe<z.ZodArray<z.ZodInt>, z.ZodTransform<Set<number>, number[]>>;
781
- isSubgraphCompatible: z.ZodBoolean;
782
- namespace: z.ZodEnum<{
783
- readonly Mainnet: "mainnet";
784
- readonly Sepolia: "sepolia";
785
- readonly Holesky: "holesky";
786
- readonly EnsTestEnv: "ens-test-env";
787
- }>;
788
- plugins: z.ZodArray<z.ZodEnum<typeof PluginName>>;
789
- databaseSchemaName: z.ZodString;
790
- dependencyInfo: z.ZodObject<{
791
- nodejs: z.ZodString;
792
- ponder: z.ZodString;
793
- ensRainbow: z.ZodString;
794
- ensRainbowSchema: z.ZodInt;
795
- }, z.core.$strict>;
796
- }, z.core.$strip>;
797
-
798
970
  /**
799
971
  * Builds a valid LabelSetId from a string.
800
972
  * @param maybeLabelSetId - The string to validate and convert to a LabelSetId.
@@ -841,427 +1013,658 @@ declare function labelHashToBytes(labelHash: LabelHash): ByteArray;
841
1013
  */
842
1014
  declare function parseNonNegativeInteger(maybeNumber: string): number;
843
1015
 
844
- declare const ChainIndexingStatusIds: {
845
- readonly Unstarted: "unstarted";
846
- readonly Backfill: "backfill";
847
- readonly Following: "following";
848
- readonly Completed: "completed";
849
- };
850
1016
  /**
851
- * ChainIndexingStatusId is the derived string union of possible Chain Indexing Status identifiers.
1017
+ * The type of indexing configuration for a chain.
852
1018
  */
853
- type ChainIndexingStatusId = (typeof ChainIndexingStatusIds)[keyof typeof ChainIndexingStatusIds];
854
- declare const OverallIndexingStatusIds: {
855
- readonly Unstarted: "unstarted";
856
- readonly Backfill: "backfill";
857
- readonly Following: "following";
858
- readonly Completed: "completed";
859
- readonly IndexerError: "indexer-error";
860
- };
861
- /**
862
- * OverallIndexingStatusId is the derived string union of possible Overall Indexing Status identifiers.
863
- */
864
- type OverallIndexingStatusId = (typeof OverallIndexingStatusIds)[keyof typeof OverallIndexingStatusIds];
865
- declare const ChainIndexingStrategyIds: {
1019
+ declare const ChainIndexingConfigTypeIds: {
1020
+ /**
1021
+ * Represents that indexing of the chain should be performed for an indefinite range.
1022
+ */
866
1023
  readonly Indefinite: "indefinite";
1024
+ /**
1025
+ * Represents that indexing of the chain should be performed for a definite range.
1026
+ */
867
1027
  readonly Definite: "definite";
868
1028
  };
869
1029
  /**
870
- * ChainIndexingStrategyIds is the derived string union of possible Chain Indexing Strategy identifiers.
1030
+ * The derived string union of possible {@link ChainIndexingConfigTypeIds}.
871
1031
  */
872
- type ChainIndexingStrategyId = (typeof ChainIndexingStrategyIds)[keyof typeof ChainIndexingStrategyIds];
1032
+ type ChainIndexingConfigTypeId = (typeof ChainIndexingConfigTypeIds)[keyof typeof ChainIndexingConfigTypeIds];
873
1033
  /**
874
- * Chain Indexing Indefinite Config
1034
+ * Chain indexing config for a chain whose indexing config `configType` is
1035
+ * {@link ChainIndexingConfigTypeIds.Indefinite}.
875
1036
  *
876
- * Configures a chain to be indexed for an indefinite range.
1037
+ * Invariants:
1038
+ * - `configType` is always `ChainIndexingConfigTypeIds.Indefinite`.
877
1039
  */
878
- interface ChainIndexingIndefiniteConfig {
1040
+ interface ChainIndexingConfigIndefinite {
879
1041
  /**
880
- * Chain indexing strategy.
1042
+ * The type of chain indexing config.
881
1043
  */
882
- strategy: typeof ChainIndexingStrategyIds.Indefinite;
1044
+ configType: typeof ChainIndexingConfigTypeIds.Indefinite;
883
1045
  /**
884
- * The block where indexing of the chain starts.
885
- *
886
- * An indexed chain always has its `startBlock` defined.
1046
+ * A {@link BlockRef} to the block where indexing of the chain should start.
887
1047
  */
888
1048
  startBlock: BlockRef;
889
1049
  /**
890
- * Indefinite chain indexing configs always have a null `endBlock`.
1050
+ * A {@link BlockRef} to the block where indexing of the chain should end.
891
1051
  */
892
1052
  endBlock?: null;
893
1053
  }
894
1054
  /**
895
- * Chain Indexing Definite Config
896
- *
897
- * Configures a chain to be indexed for a definite range.
1055
+ * Chain indexing config for a chain whose indexing config `configType` is
1056
+ * {@link ChainIndexingConfigTypeIds.Definite}.
898
1057
  *
899
1058
  * Invariants:
900
- * - `startBlock` is always before or the same as `endBlock`
1059
+ * - `configType` is always `ChainIndexingConfigTypeIds.Definite`.
1060
+ * - `startBlock` is always before or the same as `endBlock`.
901
1061
  */
902
- interface ChainIndexingDefiniteConfig {
1062
+ interface ChainIndexingConfigDefinite {
903
1063
  /**
904
- * Chain indexing strategy.
1064
+ * The type of chain indexing config.
905
1065
  */
906
- strategy: typeof ChainIndexingStrategyIds.Definite;
1066
+ configType: typeof ChainIndexingConfigTypeIds.Definite;
907
1067
  /**
908
- * The block where indexing of the chain starts.
909
- *
910
- * `startBlock` must always be defined.
1068
+ * A {@link BlockRef} to the block where indexing of the chain should start.
911
1069
  */
912
1070
  startBlock: BlockRef;
913
1071
  /**
914
- * The block where indexing of the chain ends.
915
- *
916
- * Definite chain indexing configs always have a defined `endBlock`.
1072
+ * A {@link BlockRef} to the block where indexing of the chain should end.
917
1073
  */
918
1074
  endBlock: BlockRef;
919
1075
  }
920
1076
  /**
921
- * Chain Indexing Config
1077
+ * Indexing configuration for a chain.
922
1078
  *
923
- * Configuration of an indexed chain.
1079
+ * Use the `configType` field to determine the specific type interpretation
1080
+ * at runtime.
1081
+ */
1082
+ type ChainIndexingConfig = ChainIndexingConfigIndefinite | ChainIndexingConfigDefinite;
1083
+ /**
1084
+ * The status of indexing a chain at the time an indexing status snapshot
1085
+ * is captured.
1086
+ */
1087
+ declare const ChainIndexingStatusIds: {
1088
+ /**
1089
+ * Represents that indexing of the chain is not ready to begin yet because:
1090
+ * - ENSIndexer is in its initialization phase and the data to build a
1091
+ * "true" {@link ChainIndexingSnapshot} for the chain is still being loaded; or
1092
+ * - ENSIndexer is using an omnichain indexing strategy and the
1093
+ * `omnichainIndexingCursor` is <= `config.startBlock.timestamp` for the chain's
1094
+ * {@link ChainIndexingSnapshot}.
1095
+ */
1096
+ readonly Queued: "chain-queued";
1097
+ /**
1098
+ * Represents that indexing of the chain is in progress and under a special
1099
+ * "backfill" phase that optimizes for accelerated indexing until reaching the
1100
+ * "fixed target" `backfillEndBlock`.
1101
+ */
1102
+ readonly Backfill: "chain-backfill";
1103
+ /**
1104
+ * Represents that the "backfill" phase of indexing the chain is completed
1105
+ * and that the chain is configured to be indexed for an indefinite range.
1106
+ * Therefore, indexing of the chain remains indefinitely in progress where
1107
+ * ENSIndexer will continuously work to discover and index new blocks as they
1108
+ * are added to the chain across time.
1109
+ */
1110
+ readonly Following: "chain-following";
1111
+ /**
1112
+ * Represents that indexing of the chain is completed as the chain is configured
1113
+ * to be indexed for a definite range and the indexing of all blocks through
1114
+ * that definite range is completed.
1115
+ */
1116
+ readonly Completed: "chain-completed";
1117
+ };
1118
+ /**
1119
+ * The derived string union of possible {@link ChainIndexingStatusIds}.
924
1120
  */
925
- type ChainIndexingConfig = ChainIndexingIndefiniteConfig | ChainIndexingDefiniteConfig;
1121
+ type ChainIndexingStatusId = (typeof ChainIndexingStatusIds)[keyof typeof ChainIndexingStatusIds];
926
1122
  /**
927
- * Chain Indexing Status: Unstarted
1123
+ * Chain indexing status snapshot for a chain whose `chainStatus` is
1124
+ * {@link ChainIndexingStatusIds.Queued}.
928
1125
  *
929
- * Notes:
930
- * - The "unstarted" status applies when using omnichain ordering and
931
- * the omnichainIndexingCursor from the overall indexing status <= config.startBlock.timestamp.
1126
+ * Invariants:
1127
+ * - `chainStatus` is always {@link ChainIndexingStatusIds.Queued}.
932
1128
  */
933
- interface ChainIndexingUnstartedStatus {
934
- status: typeof ChainIndexingStatusIds.Unstarted;
1129
+ interface ChainIndexingStatusSnapshotQueued {
1130
+ /**
1131
+ * The status of indexing the chain at the time the indexing status snapshot
1132
+ * was captured.
1133
+ */
1134
+ chainStatus: typeof ChainIndexingStatusIds.Queued;
1135
+ /**
1136
+ * The indexing configuration of the chain.
1137
+ */
935
1138
  config: ChainIndexingConfig;
936
1139
  }
937
1140
  /**
938
- * Chain Indexing Status: Backfill
1141
+ * Chain indexing status snapshot for a chain whose `chainStatus` is
1142
+ * {@link ChainIndexingStatusIds.Backfill}.
939
1143
  *
940
1144
  * During a backfill, special performance optimizations are applied to
941
- * index all blocks between config.startBlock and backfillEndBlock
1145
+ * index all blocks between `config.startBlock` and `backfillEndBlock`
942
1146
  * as fast as possible.
943
1147
  *
944
- * Notes:
945
- * - The backfillEndBlock is either config.endBlock (if present) or
946
- * the latest block on the chain when the ENSIndexer process started up.
947
- * Note how this means the backfillEndBlock is always a "fixed target".
948
- * - When latestIndexedBlock reaches backfillEndBlock, the backfill is complete.
949
- * The moment backfill is complete the status does not immediately transition.
950
- * Instead, internal processing is completed for a period of time while
951
- * the status remains "backfill". After this internal processing is completed
952
- * the status will change to "following" or "completed" depending on
953
- * the configured indexing strategy. If the strategy is indefinite,
954
- * changes to "following", else if the strategy is definite, changes to
955
- * "completed".
1148
+ * Note how `backfillEndBlock` is a "fixed target" that does not change during
1149
+ * the lifetime of an ENSIndexer process instance:
1150
+ * - If the `config` is {@link ChainIndexingConfigDefinite}:
1151
+ * `backfillEndBlock` is always the same as `config.endBlock`.
1152
+ * - If the `config` is {@link ChainIndexingConfigIndefinite}:
1153
+ * `backfillEndBlock` is a {@link BlockRef} to what was the latest block on the
1154
+ * chain when the ENSIndexer process was performing its initialization. Note how
1155
+ * this means that if the backfill process takes X hours to complete, because the
1156
+ * `backfillEndBlock` is a "fixed target", when `chainStatus` transitions to
1157
+ * {@link ChainIndexingStatusIds.Following} the chain will be X hours behind
1158
+ * "realtime" indexing.
1159
+ *
1160
+ * When `latestIndexedBlock` reaches `backfillEndBlock` the backfill is complete.
1161
+ * The moment backfill is complete the `chainStatus` may not immediately transition.
1162
+ * Instead, internal processing is completed for a period of time while
1163
+ * `chainStatus` remains {@link ChainIndexingStatusIds.Backfill}. After this internal
1164
+ * processing is completed `chainStatus` will transition:
1165
+ * - to {@link ChainIndexingStatusIds.Following} if the `config` is
1166
+ * {@link ChainIndexingConfigIndefinite}.
1167
+ * - to {@link ChainIndexingStatusIds.Completed} if the `config` is
1168
+ * {@link ChainIndexingConfigDefinite}.
956
1169
  *
957
1170
  * Invariants:
1171
+ * - `chainStatus` is always {@link ChainIndexingStatusIds.Backfill}.
958
1172
  * - `config.startBlock` is always before or the same as `latestIndexedBlock`
959
- * - `latestIndexedBlock` is always before or the same as `latestSyncedBlock`
960
- * - `latestSyncedBlock` is always before or the same as `backfillEndBlock`
961
- * - `backfillEndBlock` is the same as `config.endBlock` if and only if
962
- * the config is definite.
1173
+ * - `config.endBlock` is always the same as `backfillEndBlock` if and only if
1174
+ * the config is {@link ChainIndexingConfigDefinite}.
1175
+ * - `latestIndexedBlock` is always before or the same as `backfillEndBlock`
963
1176
  */
964
- interface ChainIndexingBackfillStatus {
965
- status: typeof ChainIndexingStatusIds.Backfill;
966
- config: ChainIndexingConfig;
1177
+ interface ChainIndexingStatusSnapshotBackfill {
967
1178
  /**
968
- * The block that was most recently indexed.
1179
+ * The status of indexing the chain at the time the indexing status snapshot
1180
+ * was captured.
969
1181
  */
970
- latestIndexedBlock: BlockRef;
1182
+ chainStatus: typeof ChainIndexingStatusIds.Backfill;
971
1183
  /**
972
- * The "highest" block that has been synced into RPC cache. Backfill indexing
973
- * is accelerated by cached RPC calls through this block height.
1184
+ * The indexing configuration of the chain.
974
1185
  */
975
- latestSyncedBlock: BlockRef;
1186
+ config: ChainIndexingConfig;
1187
+ /**
1188
+ * A {@link BlockRef} to the block that was most recently indexed as of the time the
1189
+ * indexing status snapshot was captured.
1190
+ */
1191
+ latestIndexedBlock: BlockRef;
976
1192
  /**
977
- * The block that is the target for finishing the backfill.
1193
+ * A {@link BlockRef} to the block where the backfill will end.
978
1194
  */
979
1195
  backfillEndBlock: BlockRef;
980
1196
  }
981
1197
  /**
982
- * Chain Indexing Status: Following
983
- *
984
- * Following occurs after the backfill of a chain is completed and represents
985
- * the process of indefinitely following (and indexing!) new blocks as they are
986
- * added to the indexed chain across time.
1198
+ * Chain indexing status snapshot for a chain whose `chainStatus` is
1199
+ * {@link ChainIndexingStatusIds.Following}.
987
1200
  *
988
1201
  * Invariants:
1202
+ * - `chainStatus` is always {@link ChainIndexingStatusIds.Following}.
1203
+ * - `config` is always {@link ChainIndexingConfigIndefinite}
989
1204
  * - `config.startBlock` is always before or the same as `latestIndexedBlock`
990
1205
  * - `latestIndexedBlock` is always before or the same as `latestKnownBlock`
991
1206
  */
992
- interface ChainIndexingFollowingStatus {
993
- status: typeof ChainIndexingStatusIds.Following;
994
- config: ChainIndexingIndefiniteConfig;
1207
+ interface ChainIndexingStatusSnapshotFollowing {
995
1208
  /**
996
- * The block that was most recently indexed.
1209
+ * The status of indexing the chain at the time the indexing status snapshot
1210
+ * was captured.
997
1211
  */
998
- latestIndexedBlock: BlockRef;
1212
+ chainStatus: typeof ChainIndexingStatusIds.Following;
999
1213
  /**
1000
- * The "highest" block that has been fetched by RPC calls and stored in
1001
- * the RPC cache as part of the indexing process.
1214
+ * The indexing configuration of the chain.
1002
1215
  */
1003
- latestKnownBlock: BlockRef;
1216
+ config: ChainIndexingConfigIndefinite;
1004
1217
  /**
1005
- * The number of seconds between `latestIndexedBlock.timestamp` and
1006
- * the current time in ENSIndexer. This represents the upper-bound worst case
1007
- * distance approximation between the latest block on the chain (independent
1008
- * of it becoming known to us) and the latest block that has completed
1009
- * indexing. The true distance to the latest block on the chain will be less
1010
- * if the latest block on the chain was not issued at the current second.
1218
+ * A {@link BlockRef} to the block that was most recently indexed as of the time the
1219
+ * indexing status snapshot was captured.
1011
1220
  */
1012
- approxRealtimeDistance: Duration;
1221
+ latestIndexedBlock: BlockRef;
1222
+ /**
1223
+ * A {@link BlockRef} to the "highest" block that has been discovered by RPCs
1224
+ * and stored in the RPC cache as of the time the indexing status snapshot was
1225
+ * captured.
1226
+ */
1227
+ latestKnownBlock: BlockRef;
1013
1228
  }
1014
1229
  /**
1015
- * Chain Indexing Status: Completed
1230
+ * Chain indexing status snapshot for a chain whose `chainStatus` is
1231
+ * {@link ChainIndexingStatusIds.Completed}.
1016
1232
  *
1017
- * Indexing of a chain is completed after the backfill when the chain is
1018
- * not configured to be indefinitely indexed.
1233
+ * After the backfill of a chain is completed, if the chain was configured
1234
+ * to be indexed for a definite range, the chain indexing status will transition to
1235
+ * {@link ChainIndexingStatusIds.Completed}.
1019
1236
  *
1020
1237
  * Invariants:
1238
+ * - `chainStatus` is always {@link ChainIndexingStatusIds.Completed}.
1239
+ * - `config` is always {@link ChainIndexingConfigDefinite}
1021
1240
  * - `config.startBlock` is always before or the same as `latestIndexedBlock`
1022
1241
  * - `latestIndexedBlock` is always the same as `config.endBlock`.
1023
1242
  */
1024
- interface ChainIndexingCompletedStatus {
1025
- status: typeof ChainIndexingStatusIds.Completed;
1026
- config: ChainIndexingDefiniteConfig;
1243
+ interface ChainIndexingStatusSnapshotCompleted {
1244
+ /**
1245
+ * The status of indexing the chain at the time the indexing status snapshot
1246
+ * was captured.
1247
+ */
1248
+ chainStatus: typeof ChainIndexingStatusIds.Completed;
1249
+ /**
1250
+ * The indexing configuration of the chain.
1251
+ */
1252
+ config: ChainIndexingConfigDefinite;
1027
1253
  /**
1028
- * The block that was most recently indexed.
1254
+ * A {@link BlockRef} to the block that was most recently indexed as of the time the
1255
+ * indexing status snapshot was captured.
1029
1256
  */
1030
1257
  latestIndexedBlock: BlockRef;
1031
1258
  }
1032
1259
  /**
1033
- * Chain Indexing Status
1260
+ * Indexing status snapshot for a single chain.
1034
1261
  *
1035
- * Use the `status` field to determine the correct type interpretation at runtime.
1262
+ * Use the `chainStatus` field to determine the specific type interpretation
1263
+ * at runtime.
1036
1264
  */
1037
- type ChainIndexingStatus = ChainIndexingUnstartedStatus | ChainIndexingBackfillStatus | ChainIndexingFollowingStatus | ChainIndexingCompletedStatus;
1265
+ type ChainIndexingStatusSnapshot = ChainIndexingStatusSnapshotQueued | ChainIndexingStatusSnapshotBackfill | ChainIndexingStatusSnapshotFollowing | ChainIndexingStatusSnapshotCompleted;
1038
1266
  /**
1039
- * Chain Indexing Status: Active
1040
- *
1041
- * Represents a chain where indexing is currently active.
1042
- * The `latestIndexedBlock` field will be available.
1267
+ * The status of omnichain indexing at the time an omnichain indexing status
1268
+ * snapshot is captured.
1043
1269
  */
1044
- type ChainIndexingActiveStatus = ChainIndexingBackfillStatus | ChainIndexingFollowingStatus;
1270
+ declare const OmnichainIndexingStatusIds: {
1271
+ /**
1272
+ * Represents that omnichain indexing is not ready to begin yet because
1273
+ * ENSIndexer is in its initialization phase and the data to build a "true"
1274
+ * {@link OmnichainIndexingStatusSnapshot} is still being loaded.
1275
+ */
1276
+ readonly Unstarted: "omnichain-unstarted";
1277
+ /**
1278
+ * Represents that omnichain indexing is in an overall "backfill" status because
1279
+ * - At least one indexed chain has a `chainStatus` of
1280
+ * {@link ChainIndexingStatusIds.Backfill}; and
1281
+ * - No indexed chain has a `chainStatus` of {@link ChainIndexingStatusIds.Following}.
1282
+ */
1283
+ readonly Backfill: "omnichain-backfill";
1284
+ /**
1285
+ * Represents that omnichain indexing is in an overall "following" status because
1286
+ * at least one indexed chain has a `chainStatus` of
1287
+ * {@link ChainIndexingStatusIds.Following}.
1288
+ */
1289
+ readonly Following: "omnichain-following";
1290
+ /**
1291
+ * Represents that omnichain indexing has completed because all indexed chains have
1292
+ * a `chainStatus` of {@link ChainIndexingStatusIds.Completed}.
1293
+ */
1294
+ readonly Completed: "omnichain-completed";
1295
+ };
1045
1296
  /**
1046
- * Chain Indexing Status: Standby
1047
- *
1048
- * Represents a chain where indexing is currently on standby (not happening).
1049
- * The `latestIndexedBlock` field will not be available.
1297
+ * The derived string union of possible {@link OmnichainIndexingStatusIds}.
1050
1298
  */
1051
- type ChainIndexingStandbyStatus = ChainIndexingUnstartedStatus | ChainIndexingCompletedStatus;
1299
+ type OmnichainIndexingStatusId = (typeof OmnichainIndexingStatusIds)[keyof typeof OmnichainIndexingStatusIds];
1052
1300
  /**
1053
- * ENSIndexer Overall Indexing Status: Unstarted
1301
+ * Omnichain indexing status snapshot when the overall `omnichainStatus` is
1302
+ * {@link OmnichainIndexingStatusIds.Unstarted}.
1054
1303
  *
1055
- * Describes the current state of indexing operations across all indexed chains
1056
- * when the overall indexing status is {@link OverallIndexingStatusIds.Unstarted}.
1304
+ * Invariants:
1305
+ * - `omnichainStatus` is always {@link OmnichainIndexingStatusIds.Unstarted}.
1306
+ * - `chains` is always a map to {@link ChainIndexingStatusSnapshotQueued} values exclusively.
1307
+ * - `omnichainIndexingCursor` is always < the `config.startBlock.timestamp` for all
1308
+ * chains with `chainStatus` of {@link ChainIndexingStatusIds.Queued}.
1057
1309
  */
1058
- interface ENSIndexerOverallIndexingUnstartedStatus {
1310
+ interface OmnichainIndexingStatusSnapshotUnstarted {
1059
1311
  /**
1060
- * Overall Indexing Status
1312
+ * The status of omnichain indexing.
1061
1313
  */
1062
- overallStatus: typeof OverallIndexingStatusIds.Unstarted;
1314
+ omnichainStatus: typeof OmnichainIndexingStatusIds.Unstarted;
1063
1315
  /**
1064
- * Indexing Status for each chain.
1065
- *
1066
- * Each chain is guaranteed to have the "unstarted" status.
1067
- * It's impossible for any chain to have status other than "unstarted".
1316
+ * The indexing status snapshot for each indexed chain.
1068
1317
  */
1069
- chains: Map<ChainId, ChainIndexingUnstartedStatus>;
1318
+ chains: Map<ChainId, ChainIndexingStatusSnapshotQueued>;
1319
+ /**
1320
+ * The timestamp of omnichain indexing progress across all indexed chains.
1321
+ */
1322
+ omnichainIndexingCursor: UnixTimestamp;
1070
1323
  }
1071
1324
  /**
1072
- * Chain Indexing Status allowed when overall status is 'backfill'.
1325
+ * The range of {@link ChainIndexingSnapshot} types allowed when the
1326
+ * overall omnichain indexing status is {@link OmnichainIndexingStatusIds.Backfill}.
1327
+ *
1328
+ * Note that this is all of the {@link ChainIndexingSnapshot} types with the exception
1329
+ * of {@link ChainIndexingStatusSnapshotFollowing}.
1073
1330
  */
1074
- type ChainIndexingStatusForBackfillOverallStatus = ChainIndexingUnstartedStatus | ChainIndexingBackfillStatus | ChainIndexingCompletedStatus;
1331
+ type ChainIndexingStatusSnapshotForOmnichainIndexingStatusSnapshotBackfill = ChainIndexingStatusSnapshotQueued | ChainIndexingStatusSnapshotBackfill | ChainIndexingStatusSnapshotCompleted;
1075
1332
  /**
1076
- * ENSIndexer Overall Indexing Status: Backfill
1333
+ * Omnichain indexing status snapshot when the `omnichainStatus` is
1334
+ * {@link OmnichainIndexingStatusIds.Backfill}.
1077
1335
  *
1078
- * Describes the current state of indexing operations across all indexed chains
1079
- * when the overall indexing status is {@link OverallIndexingStatusIds.Backfill}.
1080
- */
1081
- interface ENSIndexerOverallIndexingBackfillStatus {
1336
+ * Invariants:
1337
+ * - `omnichainStatus` is always {@link OmnichainIndexingStatusIds.Backfill}.
1338
+ * - `chains` is guaranteed to contain at least one chain with a `chainStatus` of
1339
+ * {@link ChainIndexingStatusIds.Backfill}.
1340
+ * - `chains` is guaranteed to not to contain any chain with a `chainStatus` of
1341
+ * {@link ChainIndexingStatusIds.Following}
1342
+ * - `omnichainIndexingCursor` is always < the `config.startBlock.timestamp` for all
1343
+ * chains with `chainStatus` of {@link ChainIndexingStatusIds.Queued}.
1344
+ * - `omnichainIndexingCursor` is always <= the `backfillEndBlock.timestamp` for all
1345
+ * chains with `chainStatus` of {@link ChainIndexingStatusIds.Backfill}.
1346
+ * - `omnichainIndexingCursor` is always >= the `latestIndexedBlock.timestamp` for all
1347
+ * chains with `chainStatus` of {@link ChainIndexingStatusIds.Completed}.
1348
+ * - `omnichainIndexingCursor` is always equal to the timestamp of the highest
1349
+ * `latestIndexedBlock` across all chains that have started indexing
1350
+ * (`chainStatus` is not {@link ChainIndexingStatusIds.Queued}).
1351
+ */
1352
+ interface OmnichainIndexingStatusSnapshotBackfill {
1082
1353
  /**
1083
- * Overall Indexing Status
1354
+ * The status of omnichain indexing.
1084
1355
  */
1085
- overallStatus: typeof OverallIndexingStatusIds.Backfill;
1356
+ omnichainStatus: typeof OmnichainIndexingStatusIds.Backfill;
1086
1357
  /**
1087
- * Omnichain Indexing Cursor
1088
- *
1089
- * Identifies the timestamp of the progress of omnichain indexing across
1090
- * all chains in {@link ChainIndexingBackfillStatus} status.
1091
- *
1092
- * Invariants:
1093
- * - the cursor value is guaranteed to be lower than or equal to
1094
- * the timestamp of the earliest `config.startBlock` across all chains
1095
- * in {@link ChainIndexingStandbyStatus} status.
1358
+ * The indexing status snapshot for each indexed chain.
1359
+ */
1360
+ chains: Map<ChainId, ChainIndexingStatusSnapshotForOmnichainIndexingStatusSnapshotBackfill>;
1361
+ /**
1362
+ * The timestamp of omnichain indexing progress across all indexed chains.
1096
1363
  */
1097
1364
  omnichainIndexingCursor: UnixTimestamp;
1365
+ }
1366
+ /**
1367
+ * Omnichain indexing status snapshot when the overall `omnichainStatus` is
1368
+ * {@link OmnichainIndexingStatusIds.Following}.
1369
+ *
1370
+ * Invariants:
1371
+ * - `omnichainStatus` is always {@link OmnichainIndexingStatusIds.Following}.
1372
+ * - `chains` is guaranteed to contain at least one chain with a `status` of
1373
+ * {@link ChainIndexingStatusIds.Following}.
1374
+ * - `omnichainIndexingCursor` is always < the `config.startBlock.timestamp` for all
1375
+ * chains with `chainStatus` of {@link ChainIndexingStatusIds.Queued}.
1376
+ * - `omnichainIndexingCursor` is always <= the `backfillEndBlock.timestamp` for all
1377
+ * chains with `chainStatus` of {@link ChainIndexingStatusIds.Backfill}.
1378
+ * - `omnichainIndexingCursor` is always >= the `latestIndexedBlock.timestamp` for all
1379
+ * chains with `chainStatus` of {@link ChainIndexingStatusIds.Completed}.
1380
+ * - `omnichainIndexingCursor` is always equal to the timestamp of the highest
1381
+ * `latestIndexedBlock` across all chains that have started indexing
1382
+ * (`chainStatus` is not {@link ChainIndexingStatusIds.Queued}).
1383
+ */
1384
+ interface OmnichainIndexingStatusSnapshotFollowing {
1098
1385
  /**
1099
- * Indexing Status for each chain.
1100
- *
1101
- * At least one chain is guaranteed to be in the "backfill" status.
1102
- * Each chain is guaranteed to have a status of either "unstarted",
1103
- * "backfill" or "completed". It's impossible for any chain to be
1104
- * in the "following" status.
1386
+ * The status of omnichain indexing.
1387
+ */
1388
+ omnichainStatus: typeof OmnichainIndexingStatusIds.Following;
1389
+ /**
1390
+ * The indexing status snapshot for each indexed chain.
1105
1391
  */
1106
- chains: Map<ChainId, ChainIndexingStatusForBackfillOverallStatus>;
1392
+ chains: Map<ChainId, ChainIndexingStatusSnapshot>;
1393
+ /**
1394
+ * The timestamp of omnichain indexing progress across all indexed chains.
1395
+ */
1396
+ omnichainIndexingCursor: UnixTimestamp;
1107
1397
  }
1108
1398
  /**
1109
- * ENSIndexer Overall Indexing Status: Completed
1399
+ * Omnichain indexing status snapshot when the overall `omnichainStatus` is
1400
+ * {@link OmnichainIndexingStatusIds.Completed}.
1110
1401
  *
1111
- * Describes the final state of indexing operations across all indexed chains
1112
- * when all indexed chains are configured for a definite indexing strategy and
1113
- * all indexing of that definite range is completed.
1402
+ * Invariants:
1403
+ * - `omnichainStatus` is always {@link OmnichainIndexingStatusIds.Completed}.
1404
+ * - `chains` is always a map to {@link ChainIndexingStatusSnapshotCompleted} values exclusively.
1405
+ * - `omnichainIndexingCursor` is always equal to the highest
1406
+ * `latestIndexedBlock.timestamp` for all chains.
1114
1407
  */
1115
- interface ENSIndexerOverallIndexingCompletedStatus {
1408
+ interface OmnichainIndexingStatusSnapshotCompleted {
1116
1409
  /**
1117
- * Overall Indexing Status
1410
+ * The status of omnichain indexing.
1118
1411
  */
1119
- overallStatus: typeof OverallIndexingStatusIds.Completed;
1412
+ omnichainStatus: typeof OmnichainIndexingStatusIds.Completed;
1120
1413
  /**
1121
- * Indexing Status for each chain.
1122
- *
1123
- * Each chain is guaranteed to have the "completed" status.
1124
- * It's impossible for any chain to have status other than "completed".
1414
+ * The indexing status snapshot for each indexed chain.
1415
+ */
1416
+ chains: Map<ChainId, ChainIndexingStatusSnapshotCompleted>;
1417
+ /**
1418
+ * The timestamp of omnichain indexing progress across all indexed chains.
1125
1419
  */
1126
- chains: Map<ChainId, ChainIndexingCompletedStatus>;
1420
+ omnichainIndexingCursor: UnixTimestamp;
1127
1421
  }
1128
1422
  /**
1129
- * ENSIndexer Overall Indexing Status: Following
1423
+ * Omnichain indexing status snapshot for one or more chains.
1424
+ *
1425
+ * Use the `omnichainStatus` field to determine the specific type interpretation
1426
+ * at runtime.
1427
+ */
1428
+ type OmnichainIndexingStatusSnapshot = OmnichainIndexingStatusSnapshotUnstarted | OmnichainIndexingStatusSnapshotBackfill | OmnichainIndexingStatusSnapshotCompleted | OmnichainIndexingStatusSnapshotFollowing;
1429
+ /**
1430
+ * The strategy used for indexing one or more chains.
1130
1431
  *
1131
- * Describes the state when the overall indexing status is
1132
- * {@link OverallIndexingStatusIds.Following}.
1432
+ * @see https://ponder.sh/docs/api-reference/ponder/config#parameters
1133
1433
  */
1134
- interface ENSIndexerOverallIndexingFollowingStatus {
1434
+ declare const CrossChainIndexingStrategyIds: {
1135
1435
  /**
1136
- * Overall Indexing Status
1436
+ * Represents that the indexing of events across all indexed chains will
1437
+ * proceed in a deterministic "omnichain" ordering by block timestamp, chain ID,
1438
+ * and block number.
1439
+ *
1440
+ * This strategy is "deterministic" in that the order of processing cross-chain indexed
1441
+ * events and each resulting indexed data state transition recorded in ENSDb is always
1442
+ * the same for each ENSIndexer instance operating with an equivalent
1443
+ * `ENSIndexerConfig` and ENSIndexer version. However it also has the drawbacks of:
1444
+ * - increased indexing latency that must wait for the slowest indexed chain to
1445
+ * add new blocks or to discover new blocks through the configured RPCs.
1446
+ * - if any indexed chain gets "stuck" due to chain or RPC failures, all indexed chains
1447
+ * will be affected.
1448
+ */
1449
+ readonly Omnichain: "omnichain";
1450
+ };
1451
+ /**
1452
+ * The derived string union of possible {@link CrossChainIndexingStrategyIds}.
1453
+ */
1454
+ type CrossChainIndexingStrategyId = (typeof CrossChainIndexingStrategyIds)[keyof typeof CrossChainIndexingStrategyIds];
1455
+ /**
1456
+ * Cross-chain indexing status snapshot when the `strategy` is
1457
+ * {@link CrossChainIndexingStrategyId.Omnichain}.
1458
+ *
1459
+ * Invariants:
1460
+ * - `strategy` is always {@link CrossChainIndexingStrategyId.Omnichain}.
1461
+ * - `slowestChainIndexingCursor` is always equal to
1462
+ * `omnichainSnapshot.omnichainIndexingCursor`.
1463
+ * - `snapshotTime` is always >= the "highest known block timestamp", defined as the max of:
1464
+ * - the `slowestChainIndexingCursor`.
1465
+ * - the `config.startBlock.timestamp` for all indexed chains.
1466
+ * - the `config.endBlock.timestamp` for all indexed chains with a `config.configType` of
1467
+ * {@link ChainIndexingConfigTypeIds.Definite}.
1468
+ * - the `backfillEndBlock.timestamp` for all chains with `chainStatus` of
1469
+ * {@link ChainIndexingStatusIds.Backfill}.
1470
+ * - the `latestKnownBlock.timestamp` for all chains with `chainStatus` of
1471
+ * {@link ChainIndexingStatusIds.Following}.
1472
+ */
1473
+ interface CrossChainIndexingStatusSnapshotOmnichain {
1474
+ /**
1475
+ * The strategy used for indexing one or more chains.
1137
1476
  */
1138
- overallStatus: typeof OverallIndexingStatusIds.Following;
1477
+ strategy: typeof CrossChainIndexingStrategyIds.Omnichain;
1139
1478
  /**
1140
- * Omnichain Indexing Cursor
1141
- *
1142
- * Identifies the timestamp of the progress of omnichain indexing across
1143
- * all chains in {@link ChainIndexingActiveStatus} status.
1144
- *
1145
- * Invariants:
1146
- * - the cursor value is guaranteed to be lower than or equal to
1147
- * the timestamp of the earliest `config.startBlock` across all chains
1148
- * in {@link ChainIndexingStandbyStatus} status.
1479
+ * The timestamp of the "slowest" latest indexed block timestamp
1480
+ * across all indexed chains.
1149
1481
  */
1150
- omnichainIndexingCursor: UnixTimestamp;
1482
+ slowestChainIndexingCursor: UnixTimestamp;
1151
1483
  /**
1152
- * Indexing Status for each chain.
1484
+ * The timestamp when the cross-chain indexing status snapshot was generated.
1153
1485
  *
1154
- * At least one chain is guaranteed to be in the "following" status.
1155
- * Each chain is guaranteed to have a status of either "unstarted",
1156
- * "backfill", "following" or "completed".
1486
+ * Due to possible clock skew between different systems this value must be set
1487
+ * to the max of each of the following values to ensure all invariants are followed:
1488
+ * - the current system time of the system generating this cross-chain indexing
1489
+ * status snapshot.
1490
+ * - the "highest known block timestamp" (see invariants above for full definition).
1157
1491
  */
1158
- chains: Map<ChainId, ChainIndexingStatus>;
1492
+ snapshotTime: UnixTimestamp;
1159
1493
  /**
1160
- * The maximum
1161
- * {@link ChainIndexingFollowingStatus.approxRealtimeDistance} value
1162
- * across all chains with status: 'following'.
1494
+ * The omnichain indexing status snapshot for one or more chains.
1163
1495
  */
1164
- overallApproxRealtimeDistance: Duration;
1496
+ omnichainSnapshot: OmnichainIndexingStatusSnapshot;
1165
1497
  }
1166
1498
  /**
1167
- * ENSIndexer Overall Indexing Status: Error
1499
+ * Cross-chain indexing status snapshot for one or more chains.
1168
1500
  *
1169
- * Describes the state when ENSIndexer failed to return the indexing status for
1170
- * all indexed chains.
1501
+ * Use the `strategy` field to determine the specific type interpretation
1502
+ * at runtime.
1171
1503
  *
1172
- * This state suggests an error with the "primary" ENSIndexer.
1504
+ * Currently, only omnichain indexing is supported. This type could theoretically
1505
+ * be extended to support other cross-chain indexing strategies in the future,
1506
+ * such as Ponder's "multichain" indexing strategy that indexes each chain
1507
+ * independently without deterministic ordering.
1173
1508
  */
1174
- interface ENSIndexerOverallIndexingErrorStatus {
1175
- /**
1176
- * Overall Indexing Status
1177
- */
1178
- overallStatus: typeof OverallIndexingStatusIds.IndexerError;
1179
- }
1509
+ type CrossChainIndexingStatusSnapshot = CrossChainIndexingStatusSnapshotOmnichain;
1180
1510
  /**
1181
- * ENSIndexer Overall Indexing Status
1511
+ * A "realtime" indexing status projection based on worst-case assumptions
1512
+ * from the `snapshot`.
1182
1513
  *
1183
- * Describes the overall state of indexing operations.
1514
+ * Invariants:
1515
+ * - `projectedAt` is always >= `snapshot.snapshotTime`.
1516
+ * - `worstCaseDistance` is always equal to
1517
+ * `projectedAt - snapshot.slowestChainIndexingCursor`.
1184
1518
  */
1185
- type ENSIndexerOverallIndexingStatus = ENSIndexerOverallIndexingUnstartedStatus | ENSIndexerOverallIndexingBackfillStatus | ENSIndexerOverallIndexingCompletedStatus | ENSIndexerOverallIndexingFollowingStatus | ENSIndexerOverallIndexingErrorStatus;
1519
+ type RealtimeIndexingStatusProjection = {
1520
+ /**
1521
+ * The timestamp representing "now" as of the time this projection was generated.
1522
+ */
1523
+ projectedAt: UnixTimestamp;
1524
+ /**
1525
+ * The distance between `projectedAt` and `snapshot.slowestChainIndexingCursor`.
1526
+ *
1527
+ * This is "worst-case" because it assumes all of the following:
1528
+ * - the `snapshot` (which may have `snapshot.snapshotTime < projectedAt`) is still the
1529
+ * latest snapshot and no indexing progress has been made since `snapshotTime`.
1530
+ * - each indexed chain has added a new block as of `projectedAt`.
1531
+ */
1532
+ worstCaseDistance: Duration;
1533
+ /**
1534
+ * The {@link CrossChainIndexingStatusSnapshot} that this projection is based on.
1535
+ */
1536
+ snapshot: CrossChainIndexingStatusSnapshot;
1537
+ };
1186
1538
 
1187
1539
  /**
1188
- * Serialized representation of {@link ENSIndexerOverallIndexingUnstartedStatus}
1540
+ * Serialized representation of {@link ChainIndexingStatusSnapshot}
1541
+ */
1542
+ type SerializedChainIndexingStatusSnapshot = ChainIndexingStatusSnapshot;
1543
+ /**
1544
+ * Serialized representation of {@link ChainIndexingStatusSnapshotQueued}
1545
+ */
1546
+ type SerializedChainIndexingStatusSnapshotQueued = ChainIndexingStatusSnapshotQueued;
1547
+ /**
1548
+ * Serialized representation of {@link ChainIndexingStatusSnapshotBackfill}
1549
+ */
1550
+ type SerializedChainIndexingStatusSnapshotBackfill = ChainIndexingStatusSnapshotBackfill;
1551
+ /**
1552
+ * Serialized representation of {@link ChainIndexingStatusSnapshotCompleted}
1553
+ */
1554
+ type SerializedChainIndexingStatusSnapshotCompleted = ChainIndexingStatusSnapshotCompleted;
1555
+ /**
1556
+ * Serialized representation of {@link ChainIndexingStatusSnapshotFollowing}
1557
+ */
1558
+ type SerializedChainIndexingStatusSnapshotFollowing = ChainIndexingStatusSnapshotFollowing;
1559
+ /**
1560
+ * Serialized representation of {@link OmnichainIndexingStatusSnapshotUnstarted}
1189
1561
  */
1190
- interface SerializedENSIndexerOverallIndexingUnstartedStatus extends Omit<ENSIndexerOverallIndexingUnstartedStatus, "chains"> {
1191
- chains: Record<ChainIdString, ChainIndexingUnstartedStatus>;
1562
+ interface SerializedOmnichainIndexingStatusSnapshotUnstarted extends Omit<OmnichainIndexingStatusSnapshotUnstarted, "chains"> {
1563
+ chains: Record<ChainIdString, ChainIndexingStatusSnapshotQueued>;
1192
1564
  }
1193
1565
  /**
1194
- * Serialized representation of {@link ENSIndexerOverallIndexingBackfillStatus}
1566
+ * Serialized representation of {@link OmnichainIndexingStatusSnapshotBackfill}
1195
1567
  */
1196
- interface SerializedENSIndexerOverallIndexingBackfillStatus extends Omit<ENSIndexerOverallIndexingBackfillStatus, "chains"> {
1197
- chains: Record<ChainIdString, ChainIndexingStatusForBackfillOverallStatus>;
1568
+ interface SerializedOmnichainIndexingStatusSnapshotBackfill extends Omit<OmnichainIndexingStatusSnapshotBackfill, "chains"> {
1569
+ chains: Record<ChainIdString, ChainIndexingStatusSnapshotForOmnichainIndexingStatusSnapshotBackfill>;
1198
1570
  }
1199
1571
  /**
1200
- * Serialized representation of {@link ENSIndexerOverallIndexingCompletedStatus}
1572
+ * Serialized representation of {@link OmnichainIndexingStatusSnapshotCompleted}
1201
1573
  */
1202
- interface SerializedENSIndexerOverallIndexingCompletedStatus extends Omit<ENSIndexerOverallIndexingCompletedStatus, "chains"> {
1203
- chains: Record<ChainIdString, ChainIndexingCompletedStatus>;
1574
+ interface SerializedOmnichainIndexingStatusSnapshotCompleted extends Omit<OmnichainIndexingStatusSnapshotCompleted, "chains"> {
1575
+ chains: Record<ChainIdString, ChainIndexingStatusSnapshotCompleted>;
1204
1576
  }
1205
1577
  /**
1206
- * Serialized representation of {@link ENSIndexerOverallIndexingFollowingStatus}
1578
+ * Serialized representation of {@link OmnichainIndexingStatusSnapshotFollowing}
1207
1579
  */
1208
- interface SerializedENSIndexerOverallIndexingFollowingStatus extends Omit<ENSIndexerOverallIndexingFollowingStatus, "chains"> {
1209
- chains: Record<ChainIdString, ChainIndexingStatus>;
1580
+ interface SerializedOmnichainIndexingStatusSnapshotFollowing extends Omit<OmnichainIndexingStatusSnapshotFollowing, "chains"> {
1581
+ chains: Record<ChainIdString, ChainIndexingStatusSnapshot>;
1210
1582
  }
1211
1583
  /**
1212
- * Serialized representation of {@link ENSIndexerOverallIndexingErrorStatus}
1584
+ * Serialized representation of {@link OmnichainIndexingStatusSnapshot}
1213
1585
  */
1214
- interface SerializedENSIndexerOverallIndexingErrorStatus extends ENSIndexerOverallIndexingErrorStatus {
1586
+ type SerializedOmnichainIndexingStatusSnapshot = SerializedOmnichainIndexingStatusSnapshotUnstarted | SerializedOmnichainIndexingStatusSnapshotBackfill | SerializedOmnichainIndexingStatusSnapshotCompleted | SerializedOmnichainIndexingStatusSnapshotFollowing;
1587
+ /**
1588
+ * Serialized representation of {@link CrossChainIndexingStatusSnapshotOmnichain}
1589
+ */
1590
+ interface SerializedCrossChainIndexingStatusSnapshotOmnichain extends Omit<CrossChainIndexingStatusSnapshotOmnichain, "omnichainSnapshot"> {
1591
+ omnichainSnapshot: SerializedOmnichainIndexingStatusSnapshot;
1215
1592
  }
1216
1593
  /**
1217
- * Serialized representation of {@link ENSIndexerOverallIndexingStatus}
1594
+ * Serialized representation of {@link CrossChainIndexingStatusSnapshot}
1218
1595
  */
1219
- type SerializedENSIndexerOverallIndexingStatus = SerializedENSIndexerOverallIndexingUnstartedStatus | SerializedENSIndexerOverallIndexingBackfillStatus | SerializedENSIndexerOverallIndexingCompletedStatus | SerializedENSIndexerOverallIndexingFollowingStatus | SerializedENSIndexerOverallIndexingErrorStatus;
1220
-
1596
+ type SerializedCrossChainIndexingStatusSnapshot = SerializedCrossChainIndexingStatusSnapshotOmnichain;
1221
1597
  /**
1222
- * Serialize a {@link ENSIndexerOverallIndexingStatus} object.
1598
+ * Serialized representation of {@link RealtimeIndexingStatusProjection}
1223
1599
  */
1224
- declare function deserializeENSIndexerIndexingStatus(maybeStatus: SerializedENSIndexerOverallIndexingStatus, valueLabel?: string): ENSIndexerOverallIndexingStatus;
1600
+ interface SerializedCurrentIndexingProjectionOmnichain extends Omit<RealtimeIndexingStatusProjection, "snapshot"> {
1601
+ snapshot: SerializedOmnichainIndexingStatusSnapshot;
1602
+ }
1603
+ /**
1604
+ * Serialized representation of {@link RealtimeIndexingStatusProjection}
1605
+ */
1606
+ interface SerializedRealtimeIndexingStatusProjection extends Omit<RealtimeIndexingStatusProjection, "snapshot"> {
1607
+ snapshot: SerializedCrossChainIndexingStatusSnapshot;
1608
+ }
1225
1609
 
1226
1610
  /**
1227
- * Get {@link OverallIndexingStatusId} based on indexed chains' statuses.
1228
- *
1229
- * This function decides what is the current overall indexing status,
1230
- * based on provided chain indexing statuses. The fact that chain indexing
1231
- * statuses were provided to this function guarantees there was no indexer
1232
- * error, and that the overall indexing status is never
1233
- * an {@link OverallIndexingStatusIds.IndexerError}
1611
+ * Deserialize into a {@link ChainIndexingSnapshot} object.
1234
1612
  */
1235
- declare function getOverallIndexingStatus(chains: ChainIndexingStatus[]): Exclude<OverallIndexingStatusId, typeof OverallIndexingStatusIds.IndexerError>;
1613
+ declare function deserializeChainIndexingStatusSnapshot(maybeSnapshot: SerializedChainIndexingStatusSnapshot, valueLabel?: string): ChainIndexingStatusSnapshot;
1236
1614
  /**
1237
- * Get overall approximate realtime distance across all indexed chains.
1238
- *
1239
- * @throws an error if none of the indexed chains was in the 'following' status.
1615
+ * Deserialize an {@link OmnichainIndexingStatusSnapshot} object.
1240
1616
  */
1241
- declare function getOverallApproxRealtimeDistance(chains: ChainIndexingStatus[]): Duration;
1617
+ declare function deserializeOmnichainIndexingStatusSnapshot(maybeSnapshot: SerializedOmnichainIndexingStatusSnapshot, valueLabel?: string): OmnichainIndexingStatusSnapshot;
1242
1618
  /**
1243
- * Get lowest of the highest end block across all chains which status is
1244
- * {@link ChainIndexingStatus}.
1619
+ * Deserialize an {@link CrossChainIndexingStatusSnapshot} object.
1245
1620
  */
1246
- declare function getTimestampForLowestOmnichainStartBlock(chains: ChainIndexingStatus[]): UnixTimestamp;
1621
+ declare function deserializeCrossChainIndexingStatusSnapshot(maybeSnapshot: SerializedCrossChainIndexingStatusSnapshot, valueLabel?: string): CrossChainIndexingStatusSnapshot;
1247
1622
  /**
1248
- * Get timestamp of the highest known block across all chains which status is
1249
- * {@link ChainIndexingStatusForBackfillOverallStatus}.
1623
+ * Deserialize into a {@link RealtimeIndexingStatusProjection} object.
1624
+ */
1625
+ declare function deserializeRealtimeIndexingStatusProjection(maybeProjection: SerializedRealtimeIndexingStatusProjection, valueLabel?: string): RealtimeIndexingStatusProjection;
1626
+
1627
+ /**
1628
+ * Get {@link OmnichainIndexingStatusId} based on indexed chains' statuses.
1629
+ *
1630
+ * This function decides what is the `OmnichainIndexingStatusId` is,
1631
+ * based on provided chain indexing statuses.
1632
+ *
1633
+ * @throws an error if unable to determine overall indexing status
1250
1634
  */
1251
- declare function getTimestampForHighestOmnichainKnownBlock(chains: ChainIndexingStatus[]): UnixTimestamp;
1635
+ declare function getOmnichainIndexingStatus(chains: ChainIndexingStatusSnapshot[]): OmnichainIndexingStatusId;
1252
1636
  /**
1253
- * Get Omnichain Indexing Cursor across all chains which status is
1254
- * {@link ChainIndexingActiveStatus}.
1637
+ * Get the timestamp of the lowest `config.startBlock` across all chains
1638
+ * in the provided array of {@link ChainIndexingStatusSnapshot}.
1639
+ *
1640
+ * Such timestamp is useful when presenting the "lowest" block
1641
+ * to be indexed across all chains.
1255
1642
  */
1256
- declare function getOmnichainIndexingCursor(chains: ChainIndexingActiveStatus[]): UnixTimestamp;
1643
+ declare function getTimestampForLowestOmnichainStartBlock(chains: ChainIndexingStatusSnapshot[]): UnixTimestamp;
1257
1644
  /**
1258
- * Get all chains which status is {@link ChainIndexingActiveStatus}.
1645
+ * Get the timestamp of the "highest known block" across all chains
1646
+ * in the provided array of {@link ChainIndexingStatusSnapshot}.
1647
+ *
1648
+ * Such timestamp is useful when presenting the "highest known block"
1649
+ * to be indexed across all chains.
1650
+ *
1651
+ * The "highest known block" for a chain depends on its status:
1652
+ * - `config.endBlock` for a "queued" chain,
1653
+ * - `backfillEndBlock` for a "backfill" chain,
1654
+ * - `latestIndexedBlock` for a "completed" chain,
1655
+ * - `latestKnownBlock` for a "following" chain.
1259
1656
  */
1260
- declare function getActiveChains(chains: ChainIndexingStatus[]): ChainIndexingActiveStatus[];
1657
+ declare function getTimestampForHighestOmnichainKnownBlock(chains: ChainIndexingStatusSnapshot[]): UnixTimestamp;
1261
1658
  /**
1262
- * Get all chains which status is {@link ChainIndexingStandbyStatus}.
1659
+ * Get Omnichain Indexing Cursor
1660
+ *
1661
+ * The cursor tracks the "highest" latest indexed block timestamp across
1662
+ * all indexed chains. If all chains are queued, the cursor tracks the moment
1663
+ * just before the earliest start block timestamp across those chains.
1664
+ *
1665
+ * @throws an error if no chains are provided
1263
1666
  */
1264
- declare function getStandbyChains(chains: ChainIndexingStatus[]): ChainIndexingStandbyStatus[];
1667
+ declare function getOmnichainIndexingCursor(chains: ChainIndexingStatusSnapshot[]): UnixTimestamp;
1265
1668
  /**
1266
1669
  * Create {@link ChainIndexingConfig} for given block refs.
1267
1670
  *
@@ -1270,55 +1673,63 @@ declare function getStandbyChains(chains: ChainIndexingStatus[]): ChainIndexingS
1270
1673
  */
1271
1674
  declare function createIndexingConfig(startBlock: BlockRef, endBlock: BlockRef | null): ChainIndexingConfig;
1272
1675
  /**
1273
- * Check if Chain Indexing Statuses fit the 'unstarted' overall status
1274
- * requirements:
1275
- * - All chains are guaranteed to have a status of "unstarted".
1676
+ * Check if Chain Indexing Status Snapshots fit the 'unstarted' overall status
1677
+ * snapshot requirements:
1678
+ * - All chains are guaranteed to have a status of "queued".
1276
1679
  *
1277
- * Note: This function narrows the {@link ChainIndexingStatus} type to
1278
- * {@link ChainIndexingUnstartedStatus}.
1680
+ * Note: This function narrows the {@link ChainIndexingStatusSnapshot} type to
1681
+ * {@link ChainIndexingStatusSnapshotQueued}.
1279
1682
  */
1280
- declare function checkChainIndexingStatusesForUnstartedOverallStatus(chains: ChainIndexingStatus[]): chains is ChainIndexingUnstartedStatus[];
1683
+ declare function checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotUnstarted(chains: ChainIndexingStatusSnapshot[]): chains is ChainIndexingStatusSnapshotQueued[];
1281
1684
  /**
1282
- * Check if Chain Indexing Statuses fit the 'backfill' overall status
1283
- * requirements:
1685
+ * Check if Chain Indexing Status Snapshots fit the 'backfill' overall status
1686
+ * snapshot requirements:
1284
1687
  * - At least one chain is guaranteed to be in the "backfill" status.
1285
- * - Each chain is guaranteed to have a status of either "unstarted",
1688
+ * - Each chain is guaranteed to have a status of either "queued",
1286
1689
  * "backfill" or "completed".
1287
1690
  *
1288
- * Note: This function narrows the {@linkChainIndexingStatus} type to
1289
- * {@link ChainIndexingStatusForBackfillOverallStatus}.
1691
+ * Note: This function narrows the {@link ChainIndexingStatusSnapshot} type to
1692
+ * {@link ChainIndexingStatusSnapshotForOmnichainIndexingStatusSnapshotBackfill}.
1290
1693
  */
1291
- declare function checkChainIndexingStatusesForBackfillOverallStatus(chains: ChainIndexingStatus[]): chains is ChainIndexingStatusForBackfillOverallStatus[];
1694
+ declare function checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotBackfill(chains: ChainIndexingStatusSnapshot[]): chains is ChainIndexingStatusSnapshotForOmnichainIndexingStatusSnapshotBackfill[];
1292
1695
  /**
1293
- * Checks if Chain Indexing Statuses fit the 'completed' overall status
1294
- * requirements:
1696
+ * Checks if Chain Indexing Status Snapshots fit the 'completed' overall status
1697
+ * snapshot requirements:
1295
1698
  * - All chains are guaranteed to have a status of "completed".
1296
1699
  *
1297
- * Note: This function narrows the {@linkChainIndexingStatus} type to
1298
- * {@link ChainIndexingCompletedStatus}.
1700
+ * Note: This function narrows the {@link ChainIndexingStatusSnapshot} type to
1701
+ * {@link ChainIndexingStatusSnapshotCompleted}.
1299
1702
  */
1300
- declare function checkChainIndexingStatusesForCompletedOverallStatus(chains: ChainIndexingStatus[]): chains is ChainIndexingCompletedStatus[];
1703
+ declare function checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotCompleted(chains: ChainIndexingStatusSnapshot[]): chains is ChainIndexingStatusSnapshotCompleted[];
1301
1704
  /**
1302
- * Checks Chain Indexing Statuses fit the 'following' overall status
1303
- * requirements:
1705
+ * Checks Chain Indexing Status Snapshots fit the 'following' overall status
1706
+ * snapshot requirements:
1304
1707
  * - At least one chain is guaranteed to be in the "following" status.
1305
1708
  * - Any other chain can have any status.
1306
1709
  */
1307
- declare function checkChainIndexingStatusesForFollowingOverallStatus(chains: ChainIndexingStatus[]): chains is ChainIndexingStatus[];
1710
+ declare function checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotFollowing(chains: ChainIndexingStatusSnapshot[]): chains is ChainIndexingStatusSnapshot[];
1308
1711
  /**
1309
- * Sort a list of [{@link ChainId}, {@link ChainIndexingStatus}] tuples
1712
+ * Sort a list of [{@link ChainId}, {@link ChainIndexingStatusSnapshot}] tuples
1310
1713
  * by the omnichain start block timestamp in ascending order.
1311
1714
  */
1312
- declare function sortAscChainStatusesByStartBlock<ChainStatusType extends ChainIndexingStatus>(chains: [ChainId, ChainStatusType][]): [ChainId, ChainStatusType][];
1715
+ declare function sortChainStatusesByStartBlockAsc<ChainStatusType extends ChainIndexingStatusSnapshot>(chains: [ChainId, ChainStatusType][]): [ChainId, ChainStatusType][];
1313
1716
 
1314
1717
  /**
1315
- * Serialize chain indexing statuses.
1718
+ * Create realtime indexing status projection from
1719
+ * a {@link CrossChainIndexingStatusSnapshot}.
1316
1720
  */
1317
- declare function serializeChainIndexingStatuses<ChainIndexingStatusType extends ChainIndexingStatus>(chainIndexingStatuses: Map<ChainId, ChainIndexingStatusType>): Record<ChainIdString, ChainIndexingStatusType>;
1721
+ declare function createRealtimeIndexingStatusProjection(snapshot: CrossChainIndexingStatusSnapshot, now: UnixTimestamp): RealtimeIndexingStatusProjection;
1722
+
1723
+ declare function serializeCrossChainIndexingStatusSnapshotOmnichain({ strategy, slowestChainIndexingCursor, snapshotTime, omnichainSnapshot, }: CrossChainIndexingStatusSnapshot): SerializedCrossChainIndexingStatusSnapshot;
1724
+ declare function serializeRealtimeIndexingStatusProjection(indexingProjection: RealtimeIndexingStatusProjection): SerializedRealtimeIndexingStatusProjection;
1318
1725
  /**
1319
- * Serialize a {@link ENSIndexerIndexingStatus} object.
1726
+ * Serialize chain indexing snapshots.
1320
1727
  */
1321
- declare function serializeENSIndexerIndexingStatus(indexingStatus: ENSIndexerOverallIndexingStatus): SerializedENSIndexerOverallIndexingStatus;
1728
+ declare function serializeChainIndexingSnapshots<ChainIndexingStatusSnapshotType extends ChainIndexingStatusSnapshot>(chains: Map<ChainId, ChainIndexingStatusSnapshotType>): Record<ChainIdString, ChainIndexingStatusSnapshotType>;
1729
+ /**
1730
+ * Serialize a {@link OmnichainIndexingStatusSnapshot} object.
1731
+ */
1732
+ declare function serializeOmnichainIndexingStatusSnapshot(indexingStatus: OmnichainIndexingStatusSnapshot): SerializedOmnichainIndexingStatusSnapshot;
1322
1733
 
1323
1734
  /**
1324
1735
  * Identifiers for each traceable ENS protocol.
@@ -1491,26 +1902,197 @@ interface MultichainPrimaryNameResolutionArgs {
1491
1902
  * The result of performing MultichainPrimaryNameResolution
1492
1903
  */
1493
1904
  type MultichainPrimaryNameResolutionResult = Record<ChainId, Name | null>;
1905
+ /**
1906
+ * The resolution status for an `Identity`.
1907
+ */
1908
+ declare const ResolutionStatusIds: {
1909
+ /**
1910
+ * Represents that the `Identity` is not resolved yet.
1911
+ */
1912
+ readonly Unresolved: "unresolved";
1913
+ /**
1914
+ * Represents that resolution of the `Identity` resulted in a named identity.
1915
+ */
1916
+ readonly Named: "named";
1917
+ /**
1918
+ * Represents that resolution of the `Identity` resulted in an unnamed identity.
1919
+ */
1920
+ readonly Unnamed: "unnamed";
1921
+ /**
1922
+ * Represents that attempted resolution of the `Identity` resulted in an error
1923
+ * and therefore it is unknown if the `Identity` resolves to a named or unnamed identity.
1924
+ */
1925
+ readonly Unknown: "unknown";
1926
+ };
1927
+ /**
1928
+ * The derived string union of possible {@link ResolutionStatusIds}.
1929
+ */
1930
+ type ResolutionStatusId = (typeof ResolutionStatusIds)[keyof typeof ResolutionStatusIds];
1931
+ /**
1932
+ * Represents an {@link Identity} that has not become a {@link ResolvedIdentity} yet.
1933
+ *
1934
+ * Invariants:
1935
+ * - `resolutionStatus` is always {@link ResolutionStatusIds.Unresolved}.
1936
+ */
1937
+ interface UnresolvedIdentity {
1938
+ resolutionStatus: typeof ResolutionStatusIds.Unresolved;
1939
+ /**
1940
+ * The {@link DefaultableChainId} for an ENSIP-19 primary name lookup of the
1941
+ * identity associated with `address`.
1942
+ */
1943
+ chainId: DefaultableChainId;
1944
+ /**
1945
+ * The {@link Address} of the identity.
1946
+ */
1947
+ address: Address;
1948
+ }
1949
+ /**
1950
+ * Represents an `Identity` that resolved to a primary name.
1951
+ *
1952
+ * Invariants:
1953
+ * - `resolutionStatus` is always {@link ResolutionStatusIds.Named}.
1954
+ */
1955
+ interface NamedIdentity {
1956
+ resolutionStatus: typeof ResolutionStatusIds.Named;
1957
+ /**
1958
+ * The {@link DefaultableChainId} for an ENSIP-19 primary name lookup of the
1959
+ * identity associated with `address`.
1960
+ */
1961
+ chainId: DefaultableChainId;
1962
+ /**
1963
+ * The address of the identity.
1964
+ */
1965
+ address: Address;
1966
+ /**
1967
+ * The ENSIP-19 primary name lookup result of `address` on `chainId`.
1968
+ */
1969
+ name: Name;
1970
+ }
1971
+ /**
1972
+ * Represents an `Identity` that did not resolve to a primary name.
1973
+ *
1974
+ * Invariants:
1975
+ * - `resolutionStatus` is always {@link ResolutionStatusIds.Unnamed}.
1976
+ * - `name` is always `null`.
1977
+ */
1978
+ interface UnnamedIdentity {
1979
+ resolutionStatus: typeof ResolutionStatusIds.Unnamed;
1980
+ /**
1981
+ * The {@link DefaultableChainId} for an ENSIP-19 primary name lookup of the
1982
+ * identity associated with `address`.
1983
+ */
1984
+ chainId: DefaultableChainId;
1985
+ /**
1986
+ * The address of the identity.
1987
+ */
1988
+ address: Address;
1989
+ /**
1990
+ * The ENSIP-19 primary name lookup result of `address` on `chainId`.
1991
+ */
1992
+ name: null;
1993
+ }
1994
+ /**
1995
+ * Represents an `Identity` that was attempted to be resolved but the resolution attempt
1996
+ * resulted in an error and therefore it is unknown if the `Identity` resolves to a named
1997
+ * or unnamed identity.
1998
+ *
1999
+ * Invariants:
2000
+ * - `resolutionStatus` is always {@link ResolutionStatusIds.Unknown}.
2001
+ */
2002
+ interface UnknownIdentity {
2003
+ resolutionStatus: typeof ResolutionStatusIds.Unknown;
2004
+ /**
2005
+ * The {@link DefaultableChainId} for an ENSIP-19 primary name lookup of the
2006
+ * identity associated with `address`.
2007
+ */
2008
+ chainId: DefaultableChainId;
2009
+ /**
2010
+ * The address of the identity.
2011
+ */
2012
+ address: Address;
2013
+ }
2014
+ /**
2015
+ * Represents an ENSIP-19 identity resolution result.
2016
+ *
2017
+ * Use the `resolutionStatus` field to determine the specific type interpretation
2018
+ * at runtime.
2019
+ */
2020
+ type ResolvedIdentity = NamedIdentity | UnnamedIdentity | UnknownIdentity;
2021
+ /**
2022
+ * Represents an ENSIP-19 identity resolution (which may or not have been
2023
+ * resolved to a result yet).
2024
+ *
2025
+ * Use the `resolutionStatus` field to determine the specific type interpretation
2026
+ * at runtime.
2027
+ */
2028
+ type Identity = UnresolvedIdentity | ResolvedIdentity;
1494
2029
 
2030
+ declare const getCommonCoinTypes: (namespace: ENSNamespaceId) => CoinType[];
1495
2031
  declare const DefaultRecordsSelection: {
1496
2032
  readonly mainnet: {
1497
- readonly addresses: [_ensdomains_address_encoder.CoinType, ..._ensdomains_address_encoder.CoinType[]];
2033
+ readonly addresses: CoinType[];
1498
2034
  readonly texts: ["url", "avatar", "header", "description", "email", "com.twitter", "com.farcaster", "com.github"];
1499
2035
  };
1500
2036
  readonly sepolia: {
1501
- readonly addresses: [_ensdomains_address_encoder.CoinType, ..._ensdomains_address_encoder.CoinType[]];
2037
+ readonly addresses: CoinType[];
1502
2038
  readonly texts: ["url", "avatar", "header", "description", "email", "com.twitter", "com.farcaster", "com.github"];
1503
2039
  };
1504
2040
  readonly holesky: {
1505
- readonly addresses: [_ensdomains_address_encoder.CoinType, ..._ensdomains_address_encoder.CoinType[]];
2041
+ readonly addresses: CoinType[];
1506
2042
  readonly texts: ["url", "avatar", "header", "description", "email", "com.twitter", "com.farcaster", "com.github"];
1507
2043
  };
1508
2044
  readonly "ens-test-env": {
1509
- readonly addresses: [_ensdomains_address_encoder.CoinType, ..._ensdomains_address_encoder.CoinType[]];
2045
+ readonly addresses: CoinType[];
1510
2046
  readonly texts: ["url", "avatar", "header", "description", "email", "com.twitter", "com.farcaster", "com.github"];
1511
2047
  };
1512
2048
  };
1513
2049
 
2050
+ /**
2051
+ * Gets the "chainId param" that should be used for a primary name resolution
2052
+ * request.
2053
+ *
2054
+ * ENSIP-19 defines special rules for the "chainId param" used
2055
+ * in primary name resolutions for the case that the `chainId` is the
2056
+ * ENS Root Chain Id for the provided `namespaceId`.
2057
+ *
2058
+ * Whenever this case happens, ENSIP-19 requires that the
2059
+ * "chainId param" is always set to chainId: 1 (mainnet), even if the
2060
+ * `chainId` where the primary name lookup is actually happening
2061
+ * on a non-mainnet ENS Root Chain, such as on a testnet or
2062
+ * the ens-test-env.
2063
+ *
2064
+ * @param namespaceId The namespace id for the primary name lookup.
2065
+ * @param chainId The chain id where the primary name lookup will actually happen.
2066
+ * @returns The "chainId param" that should be used for the primary name lookup.
2067
+ */
2068
+ declare const getResolvePrimaryNameChainIdParam: (chainId: DefaultableChainId, namespaceId: ENSNamespaceId) => DefaultableChainId;
2069
+ /**
2070
+ * Translates a `DefaultableChainId` a `ChainId`
2071
+ * such that if the provided `chainId` is `DEFAULT_EVM_CHAIN_ID`,
2072
+ * the `ChainId` of the ENS Root Chain for the provided `namespaceId` is returned.
2073
+ *
2074
+ * @param chainId The `DefaultableChainId` to translate.
2075
+ * @param namespaceId The namespace id for the translation.
2076
+ * @returns the translated `ChainId`.
2077
+ */
2078
+ declare const translateDefaultableChainIdToChainId: (chainId: DefaultableChainId, namespaceId: ENSNamespaceId) => ChainId;
2079
+
2080
+ /**
2081
+ * Builds an {@link UnresolvedIdentity} for the provided {@link Address},
2082
+ * {@link DefaultableChainId} and {@link ENSNamespaceId}.
2083
+ *
2084
+ * If no `chainId` is provided, uses the ENS Root Chain Id for the provided
2085
+ * `namespaceId`.
2086
+ */
2087
+ declare function buildUnresolvedIdentity(address: Address, namespaceId: ENSNamespaceId, chainId?: DefaultableChainId): UnresolvedIdentity;
2088
+ /**
2089
+ * Returns whether the provided {@link Identity} is a {@link ResolvedIdentity}.
2090
+ *
2091
+ * @param identity - The {@link Identity} to check.
2092
+ * @returns Whether the provided {@link Identity} is a {@link ResolvedIdentity}.
2093
+ */
2094
+ declare function isResolvedIdentity(identity: Identity): identity is ResolvedIdentity;
2095
+
1514
2096
  /**
1515
2097
  * API Error Response Type
1516
2098
  */
@@ -1562,36 +2144,46 @@ interface ResolvePrimaryNamesResponse extends AcceleratableResponse, TraceableRe
1562
2144
  */
1563
2145
  type ConfigResponse = ENSIndexerPublicConfig;
1564
2146
  /**
1565
- * ENSIndexer Overall Indexing Status Request
2147
+ * Represents a request to Indexing Status API.
1566
2148
  */
1567
- interface IndexingStatusRequest {
2149
+ type IndexingStatusRequest = {};
2150
+ /**
2151
+ * A status code for indexing status responses.
2152
+ */
2153
+ declare const IndexingStatusResponseCodes: {
1568
2154
  /**
1569
- * Max Realtime Distance (optional)
1570
- *
1571
- * A duration value in seconds, representing the max allowed distance
1572
- * between the latest indexed block of each chain and the “tip” of
1573
- * all indexed chains. Setting this parameter influences the HTTP response
1574
- * code as follows:
1575
- * - Success (200 OK): The latest indexed block of each chain
1576
- * is within the requested distance from realtime.
1577
- * - Service Unavailable (503): The latest indexed block of each chain
1578
- * is NOT within the requested distance from realtime.
1579
- */
1580
- maxRealtimeDistance?: Duration;
1581
- }
2155
+ * Represents that the indexing status is available.
2156
+ */
2157
+ readonly Ok: "ok";
2158
+ /**
2159
+ * Represents that the indexing status is unavailable.
2160
+ */
2161
+ readonly Error: "error";
2162
+ };
1582
2163
  /**
1583
- * ENSIndexer Overall Indexing Status Response
2164
+ * The derived string union of possible {@link IndexingStatusResponseCodes}.
1584
2165
  */
1585
- type IndexingStatusResponse = ENSIndexerOverallIndexingStatus;
2166
+ type IndexingStatusResponseCode = (typeof IndexingStatusResponseCodes)[keyof typeof IndexingStatusResponseCodes];
1586
2167
  /**
1587
- * ENSIndexer Overall Indexing Status Response Codes
1588
- *
1589
- * Define a custom response code for known responses.
2168
+ * An indexing status response when the indexing status is available.
1590
2169
  */
1591
- declare const IndexingStatusResponseCodes: {
1592
- readonly IndexerError: 512;
1593
- readonly RequestedDistanceNotAchievedError: 513;
2170
+ type IndexingStatusResponseOk = {
2171
+ responseCode: typeof IndexingStatusResponseCodes.Ok;
2172
+ realtimeProjection: RealtimeIndexingStatusProjection;
2173
+ };
2174
+ /**
2175
+ * An indexing status response when the indexing status is unavailable.
2176
+ */
2177
+ type IndexingStatusResponseError = {
2178
+ responseCode: typeof IndexingStatusResponseCodes.Error;
1594
2179
  };
2180
+ /**
2181
+ * Indexing status response.
2182
+ *
2183
+ * Use the `responseCode` field to determine the specific type interpretation
2184
+ * at runtime.
2185
+ */
2186
+ type IndexingStatusResponse = IndexingStatusResponseOk | IndexingStatusResponseError;
1595
2187
 
1596
2188
  /**
1597
2189
  * Default ENSNode API endpoint URL
@@ -1674,9 +2266,10 @@ declare class ENSNodeClient {
1674
2266
  /**
1675
2267
  * Resolves the primary name of a specified address (Reverse Resolution) on a specific chain.
1676
2268
  *
1677
- * If the `address` specifies a valid [ENSIP-19 Default Name](https://docs.ens.domains/ensip/19/#default-primary-name),
1678
- * the Default Name will be returned. You _may_ query the Default EVM Chain Id (`0`) in order to
1679
- * determine the `address`'s Default Name directly.
2269
+ * If the chainId-specific Primary Name is not defined, but the `address` specifies a valid
2270
+ * [ENSIP-19 Default Name](https://docs.ens.domains/ensip/19/#default-primary-name), the Default
2271
+ * Name will be returned. You _may_ query the Default EVM Chain Id (`0`) in order to determine the
2272
+ * `address`'s Default Name directly.
1680
2273
  *
1681
2274
  * The returned Primary Name, if set, is guaranteed to be a [Normalized Name](https://ensnode.io/docs/reference/terminology#normalized-name).
1682
2275
  * If the primary name set for the address is not normalized, `null` is returned as if no primary name was set.
@@ -1708,13 +2301,14 @@ declare class ENSNodeClient {
1708
2301
  /**
1709
2302
  * Resolves the primary names of a specified address across multiple chains.
1710
2303
  *
1711
- * If the `address` specifies a valid [ENSIP-19 Default Name](https://docs.ens.domains/ensip/19/#default-primary-name),
1712
- * the Default Name will be returned for all chainIds for which there is not a chain-specific
1713
- * Primary Name. To avoid misuse, you _may not_ query the Default EVM Chain Id (`0`) directly, and
1714
- * should rely on the aforementioned per-chain defaulting behavior.
2304
+ * For each Primary Name, if the chainId-specific Primary Name is not defined, but the `address`
2305
+ * specifies a valid [ENSIP-19 Default Name](https://docs.ens.domains/ensip/19/#default-primary-name),
2306
+ * the Default Name will be returned. You _may not_ query the Default EVM Chain Id (`0`) directly,
2307
+ * and should rely on the aforementioned per-chain defaulting behavior.
1715
2308
  *
1716
2309
  * Each returned Primary Name, if set, is guaranteed to be a [Normalized Name](https://ensnode.io/docs/reference/terminology#normalized-name).
1717
- * If the primary name set for the address on any chain is not normalized, `null` is returned for that chain as if no primary name was set.
2310
+ * If the primary name set for the address on any chain is not normalized, `null` is returned for
2311
+ * that chain as if no primary name was set.
1718
2312
  *
1719
2313
  * @param address The Address whose Primary Names to resolve
1720
2314
  * @param options additional options
@@ -1732,12 +2326,12 @@ declare class ENSNodeClient {
1732
2326
  *
1733
2327
  * console.log(names);
1734
2328
  * // {
1735
- * // "1": "gregskril.eth",
1736
- * // "10": "gregskril.eth",
1737
- * // "8453": "greg.base.eth", // base-specific Primary Name!
1738
- * // "42161": "gregskril.eth",
1739
- * // "59144": "gregskril.eth",
1740
- * // "534352": "gregskril.eth"
2329
+ * // "1": "gregskril.eth", // Default Primary Name
2330
+ * // "10": "gregskril.eth", // Default Primary Name
2331
+ * // "8453": "greg.base.eth", // Base-specific Primary Name!
2332
+ * // "42161": "gregskril.eth", // Default Primary Name
2333
+ * // "59144": "gregskril.eth", // Default Primary Name
2334
+ * // "534352": "gregskril.eth" // Default Primary Name
1741
2335
  * // }
1742
2336
  *
1743
2337
  * // Resolve the address' Primary Names on specific chain Ids
@@ -1766,27 +2360,34 @@ declare class ENSNodeClient {
1766
2360
  /**
1767
2361
  * Fetch ENSNode Indexing Status
1768
2362
  *
1769
- * Fetch the ENSNode's multichain indexing status.
1770
- *
1771
- * @param options additional options
1772
- * @param options.maxRealtimeDistance the max allowed distance between the
1773
- * latest indexed block of each chain and the "tip" of all indexed chains.
1774
- * Setting this parameter influences the HTTP response code as follows:
1775
- * - Success (200 OK): The latest indexed block of each chain is within the
1776
- * requested distance from realtime.
1777
- * - Service Unavailable (503): The latest indexed block of each chain is NOT
1778
- * within the requested distance from realtime.
1779
- *
1780
2363
  * @returns {IndexingStatusResponse}
1781
2364
  *
1782
2365
  * @throws if the ENSNode request fails
1783
2366
  * @throws if the ENSNode API returns an error response
1784
2367
  * @throws if the ENSNode response breaks required invariants
1785
2368
  */
1786
- indexingStatus(options?: IndexingStatusRequest): Promise<IndexingStatusResponse>;
2369
+ indexingStatus(): Promise<IndexingStatusResponse>;
2370
+ }
2371
+
2372
+ /**
2373
+ * Serialized representation of {@link IndexingStatusResponseError}.
2374
+ */
2375
+ type SerializedIndexingStatusResponseError = IndexingStatusResponseError;
2376
+ /**
2377
+ * Serialized representation of {@link IndexingStatusResponseOk}.
2378
+ */
2379
+ interface SerializedIndexingStatusResponseOk extends Omit<IndexingStatusResponseOk, "realtimeProjection"> {
2380
+ realtimeProjection: SerializedRealtimeIndexingStatusProjection;
1787
2381
  }
2382
+ /**
2383
+ * Serialized representation of {@link IndexingStatusResponse}.
2384
+ */
2385
+ type SerializedIndexingStatusResponse = SerializedIndexingStatusResponseOk | SerializedIndexingStatusResponseError;
1788
2386
 
1789
2387
  declare function deserializeErrorResponse(maybeErrorResponse: unknown): ErrorResponse;
2388
+ declare function deserializeIndexingStatusResponse(maybeResponse: SerializedIndexingStatusResponse): IndexingStatusResponse;
2389
+
2390
+ declare function serializeIndexingStatusResponse(response: IndexingStatusResponse): SerializedIndexingStatusResponse;
1790
2391
 
1791
2392
  declare class ClientError extends Error {
1792
2393
  details?: unknown;
@@ -1794,4 +2395,4 @@ declare class ClientError extends Error {
1794
2395
  static fromErrorResponse({ message, details }: ErrorResponse): ClientError;
1795
2396
  }
1796
2397
 
1797
- export { ATTR_PROTOCOL_NAME, ATTR_PROTOCOL_STEP, ATTR_PROTOCOL_STEP_RESULT, type AcceleratableRequest, type AcceleratableResponse, type AccountId, BASENAMES_NODE, type BlockNumber, type BlockRef, type Blockrange, type Cache, type ChainId, type ChainIdString, type ChainIndexingActiveStatus, type ChainIndexingBackfillStatus, type ChainIndexingCompletedStatus, type ChainIndexingConfig, type ChainIndexingDefiniteConfig, type ChainIndexingFollowingStatus, type ChainIndexingIndefiniteConfig, type ChainIndexingStandbyStatus, type ChainIndexingStatus, type ChainIndexingStatusForBackfillOverallStatus, type ChainIndexingStatusId, ChainIndexingStatusIds, type ChainIndexingStrategyId, ChainIndexingStrategyIds, type ChainIndexingUnstartedStatus, ClientError, type ClientOptions, type ConfigResponse, DEFAULT_ENSNODE_API_URL, DEFAULT_EVM_CHAIN_ID, DEFAULT_EVM_COIN_TYPE, type Datetime, type DatetimeISO8601, type DeepPartial, DefaultRecordsSelection, type DependencyInfo, type Duration, type ENSIndexerOverallIndexingBackfillStatus, type ENSIndexerOverallIndexingCompletedStatus, type ENSIndexerOverallIndexingErrorStatus, type ENSIndexerOverallIndexingFollowingStatus, type ENSIndexerOverallIndexingStatus, type ENSIndexerOverallIndexingUnstartedStatus, type ENSIndexerPublicConfig, ENSNodeClient, ETH_COIN_TYPE, ETH_NODE, type EncodedLabelHash, type EnsRainbowClientLabelSet, type EnsRainbowServerLabelSet, type ErrorResponse, type ForwardResolutionArgs, ForwardResolutionProtocolStep, type ForwardResolutionResult, type IndexingStatusRequest, type IndexingStatusResponse, IndexingStatusResponseCodes, LINEANAMES_NODE, type Label, type LabelHash, type LabelSetId, type LabelSetVersion, LruCache, type MultichainPrimaryNameResolutionArgs, type MultichainPrimaryNameResolutionResult, type Name, type Node, type OverallIndexingStatusId, OverallIndexingStatusIds, PROTOCOL_ATTRIBUTE_PREFIX, PluginName, type ProtocolSpan, type ProtocolSpanTreeNode, type ProtocolTrace, REVERSE_ROOT_NODES, ROOT_NODE, type ResolvePrimaryNameRequest, type ResolvePrimaryNameResponse, type ResolvePrimaryNamesRequest, type ResolvePrimaryNamesResponse, type ResolveRecordsRequest, type ResolveRecordsResponse, type ResolverRecordsResponse, type ResolverRecordsResponseBase, type ResolverRecordsSelection, type ReverseResolutionArgs, ReverseResolutionProtocolStep, type ReverseResolutionResult, type RpcUrl, type SerializedENSIndexerOverallIndexingBackfillStatus, type SerializedENSIndexerOverallIndexingCompletedStatus, type SerializedENSIndexerOverallIndexingErrorStatus, type SerializedENSIndexerOverallIndexingFollowingStatus, type SerializedENSIndexerOverallIndexingStatus, type SerializedENSIndexerOverallIndexingUnstartedStatus, type SerializedENSIndexerPublicConfig, type SerializedIndexedChainIds, TraceableENSProtocol, type TraceableRequest, type TraceableResponse, type UnixTimestamp, type UrlString, accountIdEqual, addrReverseLabel, bigintToCoinType, buildEnsRainbowClientLabelSet, buildLabelSetId, buildLabelSetVersion, checkChainIndexingStatusesForBackfillOverallStatus, checkChainIndexingStatusesForCompletedOverallStatus, checkChainIndexingStatusesForFollowingOverallStatus, checkChainIndexingStatusesForUnstartedOverallStatus, coinTypeReverseLabel, coinTypeToEvmChainId, createIndexingConfig, deserializeBlockNumber, deserializeBlockRef, deserializeBlockrange, deserializeChainId, deserializeDatetime, deserializeDuration, deserializeENSIndexerIndexingStatus, deserializeENSIndexerPublicConfig, deserializeErrorResponse, deserializeUrl, encodeLabelHash, evmChainIdToCoinType, getActiveChains, getNameHierarchy, getOmnichainIndexingCursor, getOverallApproxRealtimeDistance, getOverallIndexingStatus, getStandbyChains, getTimestampForHighestOmnichainKnownBlock, getTimestampForLowestOmnichainStartBlock, interpretLiteralLabel, interpretLiteralName, invariant_isSubgraphCompatibleRequirements, invariant_reverseResolversPluginNeedsResolverRecords, isLabelIndexable, isNormalizedLabel, isNormalizedName, isSelectionEmpty, isSubgraphCompatible, labelHashToBytes, makeDatabaseSchemaNameSchema, makeDependencyInfoSchema, makeENSIndexerPublicConfigSchema, makeFullyPinnedLabelSetSchema, makeIndexedChainIdsSchema, makeLabelSetIdSchema, makeLabelSetVersionSchema, makePluginsListSchema, makeSubdomainNode, maybeHealLabelByReverseAddress, parseNonNegativeInteger, parseReverseName, reverseName, serializeChainId, serializeChainIndexingStatuses, serializeDatetime, serializeENSIndexerIndexingStatus, serializeENSIndexerPublicConfig, serializeIndexedChainIds, serializeUrl, sortAscChainStatusesByStartBlock, uint256ToHex32, uniq, validateSupportedLabelSetAndVersion };
2398
+ export { ADDR_REVERSE_NODE, ATTR_PROTOCOL_NAME, ATTR_PROTOCOL_STEP, ATTR_PROTOCOL_STEP_RESULT, type AcceleratableRequest, type AcceleratableResponse, type AccountId, BASENAMES_NODE, type BlockNumber, type BlockRef, type Blockrange, type Cache, type ChainId, type ChainIdString, type ChainIndexingConfig, type ChainIndexingConfigDefinite, type ChainIndexingConfigIndefinite, type ChainIndexingConfigTypeId, ChainIndexingConfigTypeIds, type ChainIndexingStatusId, ChainIndexingStatusIds, type ChainIndexingStatusSnapshot, type ChainIndexingStatusSnapshotBackfill, type ChainIndexingStatusSnapshotCompleted, type ChainIndexingStatusSnapshotFollowing, type ChainIndexingStatusSnapshotForOmnichainIndexingStatusSnapshotBackfill, type ChainIndexingStatusSnapshotQueued, ClientError, type ClientOptions, type ConfigResponse, type CrossChainIndexingStatusSnapshot, type CrossChainIndexingStatusSnapshotOmnichain, type CrossChainIndexingStrategyId, CrossChainIndexingStrategyIds, DEFAULT_ENSNODE_API_URL, DEFAULT_EVM_CHAIN_ID, DEFAULT_EVM_COIN_TYPE, type DNSEncodedLiteralName, type DNSEncodedName, type DNSEncodedPartiallyInterpretedName, type Datetime, type DatetimeISO8601, type DeepPartial, DefaultRecordsSelection, type DefaultableChainId, type Duration, type ENSIndexerPublicConfig, type ENSIndexerVersionInfo, ENSNodeClient, ETH_COIN_TYPE, ETH_NODE, type EncodedLabelHash, type EnsRainbowClientLabelSet, type EnsRainbowServerLabelSet, type ErrorResponse, type ForwardResolutionArgs, ForwardResolutionProtocolStep, type ForwardResolutionResult, type Identity, type IndexingStatusRequest, type IndexingStatusResponse, type IndexingStatusResponseCode, IndexingStatusResponseCodes, type IndexingStatusResponseError, type IndexingStatusResponseOk, type InterpretedLabel, type InterpretedName, LINEANAMES_NODE, type Label, type LabelHash, type LabelSetId, type LabelSetVersion, type LiteralLabel, type LiteralName, LruCache, type MultichainPrimaryNameResolutionArgs, type MultichainPrimaryNameResolutionResult, type Name, type NamedIdentity, type Node, type NormalizedName, type OmnichainIndexingStatusId, OmnichainIndexingStatusIds, type OmnichainIndexingStatusSnapshot, type OmnichainIndexingStatusSnapshotBackfill, type OmnichainIndexingStatusSnapshotCompleted, type OmnichainIndexingStatusSnapshotFollowing, type OmnichainIndexingStatusSnapshotUnstarted, PROTOCOL_ATTRIBUTE_PREFIX, PluginName, type ProtocolSpan, type ProtocolSpanTreeNode, type ProtocolTrace, ROOT_NODE, type RealtimeIndexingStatusProjection, type ResolutionStatusId, ResolutionStatusIds, type ResolvePrimaryNameRequest, type ResolvePrimaryNameResponse, type ResolvePrimaryNamesRequest, type ResolvePrimaryNamesResponse, type ResolveRecordsRequest, type ResolveRecordsResponse, type ResolvedIdentity, type ResolverRecordsResponse, type ResolverRecordsResponseBase, type ResolverRecordsSelection, type ReverseResolutionArgs, ReverseResolutionProtocolStep, type ReverseResolutionResult, type RpcUrl, type SerializedChainIndexingStatusSnapshot, type SerializedChainIndexingStatusSnapshotBackfill, type SerializedChainIndexingStatusSnapshotCompleted, type SerializedChainIndexingStatusSnapshotFollowing, type SerializedChainIndexingStatusSnapshotQueued, type SerializedCrossChainIndexingStatusSnapshot, type SerializedCrossChainIndexingStatusSnapshotOmnichain, type SerializedCurrentIndexingProjectionOmnichain, type SerializedENSIndexerPublicConfig, type SerializedENSIndexerVersionInfo, type SerializedIndexedChainIds, type SerializedIndexingStatusResponse, type SerializedIndexingStatusResponseError, type SerializedIndexingStatusResponseOk, type SerializedOmnichainIndexingStatusSnapshot, type SerializedOmnichainIndexingStatusSnapshotBackfill, type SerializedOmnichainIndexingStatusSnapshotCompleted, type SerializedOmnichainIndexingStatusSnapshotFollowing, type SerializedOmnichainIndexingStatusSnapshotUnstarted, type SerializedRealtimeIndexingStatusProjection, type SubgraphInterpretedLabel, type SubgraphInterpretedName, TraceableENSProtocol, type TraceableRequest, type TraceableResponse, type UnixTimestamp, type UnknownIdentity, type UnnamedIdentity, type UnresolvedIdentity, type UrlString, accountIdEqual, addrReverseLabel, asLowerCaseAddress, beautifyName, bigintToCoinType, buildEnsRainbowClientLabelSet, buildLabelSetId, buildLabelSetVersion, buildUnresolvedIdentity, checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotBackfill, checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotCompleted, checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotFollowing, checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotUnstarted, coinTypeReverseLabel, coinTypeToEvmChainId, createIndexingConfig, createRealtimeIndexingStatusProjection, decodeDNSEncodedLiteralName, decodeDNSEncodedName, deserializeBlockNumber, deserializeBlockRef, deserializeBlockrange, deserializeChainId, deserializeChainIndexingStatusSnapshot, deserializeCrossChainIndexingStatusSnapshot, deserializeDatetime, deserializeDuration, deserializeENSIndexerPublicConfig, deserializeErrorResponse, deserializeIndexingStatusResponse, deserializeOmnichainIndexingStatusSnapshot, deserializeRealtimeIndexingStatusProjection, deserializeUnixTimestamp, deserializeUrl, encodeLabelHash, evmChainIdToCoinType, getCommonCoinTypes, getNameHierarchy, getOmnichainIndexingCursor, getOmnichainIndexingStatus, getResolvePrimaryNameChainIdParam, getTimestampForHighestOmnichainKnownBlock, getTimestampForLowestOmnichainStartBlock, interpretedLabelsToInterpretedName, isHttpProtocol, isNormalizedLabel, isNormalizedName, isResolvedIdentity, isSelectionEmpty, isSubgraphCompatible, isWebSocketProtocol, labelHashToBytes, labelhashLiteralLabel, literalLabelToInterpretedLabel, literalLabelsToInterpretedName, literalLabelsToLiteralName, makeSubdomainNode, parseNonNegativeInteger, parseReverseName, reverseName, serializeChainId, serializeChainIndexingSnapshots, serializeCrossChainIndexingStatusSnapshotOmnichain, serializeDatetime, serializeENSIndexerPublicConfig, serializeIndexedChainIds, serializeIndexingStatusResponse, serializeOmnichainIndexingStatusSnapshot, serializeRealtimeIndexingStatusProjection, serializeUrl, sortChainStatusesByStartBlockAsc, translateDefaultableChainIdToChainId, uint256ToHex32, uniq, validateSupportedLabelSetAndVersion };