dash-platform-sdk 1.6.2 → 1.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dash-platform-sdk",
3
- "version": "1.6.2",
3
+ "version": "1.6.3",
4
4
  "main": "index.js",
5
5
  "description": "Lightweight SDK for accessing Dash Platform blockchain",
6
6
  "repository": {
@@ -18,6 +18,12 @@ export type { GRPCOptions, GRPCPool, QuorumKeyProvider };
18
18
  export interface SDKOptions {
19
19
  network: Network;
20
20
  grpc?: GRPCOptions;
21
+ /**
22
+ * Deadline of a single request attempt in milliseconds, the request is aborted and retried on another node when it expires.
23
+ * Shorthand for `grpc.requestTimeout`, which takes precedence. Streams and long-polling requests are not limited by it.
24
+ * Default is 10 seconds
25
+ */
26
+ requestTimeout?: number;
21
27
  /** Custom source of quorum public keys for proof verification, Platform Explorer is used if not set **/
22
28
  quorumKeyProvider?: QuorumKeyProvider;
23
29
  /**
@@ -59,7 +59,10 @@ export class DashPlatformSDK {
59
59
  if (customPool != null && customPool.network !== this.network) {
60
60
  throw new Error(`Custom GRPC pool network (${customPool.network}) does not match SDK network (${this.network})`);
61
61
  }
62
- this._initialize(customPool ?? new GRPCConnectionPool(this.network, this.options?.grpc));
62
+ this._initialize(customPool ?? new GRPCConnectionPool(this.network, {
63
+ ...this.options?.grpc,
64
+ requestTimeout: this.options?.grpc?.requestTimeout ?? this.options?.requestTimeout
65
+ }));
63
66
  }
64
67
  /**
65
68
  * @private
@@ -111,7 +114,10 @@ export class DashPlatformSDK {
111
114
  throw new Error(`Custom GRPC pool is bound to ${customPool.network}, pass a pool for ${network} with setGRPCPool() instead`);
112
115
  }
113
116
  this.network = network;
114
- this._initialize(customPool ?? new GRPCConnectionPool(this.network, this.options?.grpc));
117
+ this._initialize(customPool ?? new GRPCConnectionPool(this.network, {
118
+ ...this.options?.grpc,
119
+ requestTimeout: this.options?.grpc?.requestTimeout ?? this.options?.requestTimeout
120
+ }));
115
121
  }
116
122
  /**
117
123
  * Replaces source of quorum public keys used for proof verification.
@@ -1,5 +1,5 @@
1
1
  import { DocumentTransitionParams, DocumentTransitionType } from '../../types.js';
2
- import { AggregateDocumentsQuery, AggregateProofQuery, CompositeSubQuery, DocumentActionFeeAgreementWASM, DocumentsQuery, DocumentWASM, HavingClause, IdentifierLike, IdentifierWASM, PlatformVersionLike, ProvenRankedEntry, ProvenRankedPage, StateTransitionWASM, WhereClause } from 'pshenmic-dpp';
2
+ import { AggregateDocumentsQuery, AggregateProofQuery, CompositeSubQuery, DataContractWASM, DocumentActionFeeAgreementWASM, DocumentsQuery, DocumentWASM, HavingClause, IdentifierLike, IdentifierWASM, PlatformVersionLike, ProvenRankedEntry, ProvenRankedPage, StateTransitionWASM, WhereClause } from 'pshenmic-dpp';
3
3
  import { GRPCPool } from '../grpcConnectionPool.js';
4
4
  import { QuorumKeyProvider } from '../quorumKeyProvider.js';
5
5
  import { DocumentsAggregate } from './queryAggregate.js';
@@ -35,7 +35,7 @@ export declare class DocumentsController {
35
35
  /**
36
36
  * Make a query for documents retrieval from the network.
37
37
  *
38
- * @param dataContractId {IdentifierLike} Identifier of the Data Contract where fetch documents from
38
+ * @param dataContractLike {IdentifierLike | DataContractWASM} Identifier of the Data Contract where fetch documents from or Data contract instance
39
39
  * @param documentType {string} Document type of the data contract
40
40
  * @param where {object=} Where query clauses according syntax https://docs.dash.org/projects/platform/en/stable/docs/reference/query-syntax.html
41
41
  * @param orderBy {object=} Order by clauses according syntax https://docs.dash.org/projects/platform/en/stable/docs/reference/query-syntax.html
@@ -43,7 +43,7 @@ export declare class DocumentsController {
43
43
  * @param startAt {IdentifierLike=} Optional offset, where startAt is an identifier of the document. Use identifier of last item in previous response
44
44
  * @param startAfter {IdentifierLike=} Same as previous, but with exclusion. Cannot be set if startAt already provided
45
45
  */
46
- query(dataContractId: IdentifierLike, documentType: string, where?: WhereClause[], orderBy?: string[][], limit?: number, startAt?: IdentifierWASM, startAfter?: IdentifierWASM): Promise<DocumentWASM[]>;
46
+ query(dataContractLike: IdentifierLike | DataContractWASM, documentType: string, where?: WhereClause[], orderBy?: string[][], limit?: number, startAt?: IdentifierWASM, startAfter?: IdentifierWASM): Promise<DocumentWASM[]>;
47
47
  /**
48
48
  * Counts documents matching a query. Without `groupBy` returns one entry with the total,
49
49
  * with `groupBy` one entry per group
@@ -43,7 +43,7 @@ export class DocumentsController {
43
43
  /**
44
44
  * Make a query for documents retrieval from the network.
45
45
  *
46
- * @param dataContractId {IdentifierLike} Identifier of the Data Contract where fetch documents from
46
+ * @param dataContractLike {IdentifierLike | DataContractWASM} Identifier of the Data Contract where fetch documents from or Data contract instance
47
47
  * @param documentType {string} Document type of the data contract
48
48
  * @param where {object=} Where query clauses according syntax https://docs.dash.org/projects/platform/en/stable/docs/reference/query-syntax.html
49
49
  * @param orderBy {object=} Order by clauses according syntax https://docs.dash.org/projects/platform/en/stable/docs/reference/query-syntax.html
@@ -51,11 +51,11 @@ export class DocumentsController {
51
51
  * @param startAt {IdentifierLike=} Optional offset, where startAt is an identifier of the document. Use identifier of last item in previous response
52
52
  * @param startAfter {IdentifierLike=} Same as previous, but with exclusion. Cannot be set if startAt already provided
53
53
  */
54
- async query(dataContractId, documentType, where, orderBy, limit, startAt, startAfter) {
54
+ async query(dataContractLike, documentType, where, orderBy, limit, startAt, startAfter) {
55
55
  if (startAfter != null && startAt != null) {
56
56
  throw new Error('You may only set either startAfter or startAt at once');
57
57
  }
58
- return await query(this.grpcPool, this.quorumKeyProvider, new IdentifierWASM(dataContractId), documentType, where, orderBy, limit ?? 100, startAt, startAfter);
58
+ return await query(this.grpcPool, this.quorumKeyProvider, dataContractLike, documentType, where, orderBy, limit ?? 100, startAt, startAfter);
59
59
  }
60
60
  /**
61
61
  * Counts documents matching a query. Without `groupBy` returns one entry with the total,
@@ -1,4 +1,4 @@
1
- import { DocumentWASM, IdentifierLike, IdentifierWASM, WhereClause } from 'pshenmic-dpp';
1
+ import { DataContractWASM, DocumentWASM, IdentifierLike, IdentifierWASM, WhereClause } from 'pshenmic-dpp';
2
2
  import { GRPCPool } from '../grpcConnectionPool.js';
3
3
  import { QuorumKeyProvider } from '../quorumKeyProvider.js';
4
- export default function query(grpcPool: GRPCPool, quorumKeyProvider: QuorumKeyProvider, dataContractId: IdentifierLike, documentTypeName: string, where?: WhereClause[], orderBy?: string[][], limit?: number | undefined, startAt?: IdentifierWASM, startAfter?: IdentifierWASM): Promise<DocumentWASM[]>;
4
+ export default function query(grpcPool: GRPCPool, quorumKeyProvider: QuorumKeyProvider, dataContractLike: IdentifierLike | DataContractWASM, documentTypeName: string, where?: WhereClause[], orderBy?: string[][], limit?: number | undefined, startAt?: IdentifierWASM, startAfter?: IdentifierWASM): Promise<DocumentWASM[]>;
@@ -1,14 +1,16 @@
1
- import { IdentifierWASM, verifyDocumentsProof } from 'pshenmic-dpp';
1
+ import { DataContractWASM, verifyDocumentsProof } from 'pshenmic-dpp';
2
2
  import { DAPI_DEFAULT_LIMIT } from '../constants.js';
3
3
  import getDataContractByIdentifier from '../dataContracts/getDataContractByIdentifier.js';
4
4
  import QueryExecutor from '../QueryExecutor.js';
5
5
  import { createDocumentsV1Request, getDocumentsV1Data, getDocumentsV1Proof, toDocuments, toOrderClauses, toStart, toWhereClauses } from './v1.js';
6
- export default async function query(grpcPool, quorumKeyProvider, dataContractId, documentTypeName, where, orderBy, limit = 100, startAt, startAfter) {
7
- const dataContract = await getDataContractByIdentifier(grpcPool, quorumKeyProvider, dataContractId);
6
+ export default async function query(grpcPool, quorumKeyProvider, dataContractLike, documentTypeName, where, orderBy, limit = 100, startAt, startAfter) {
7
+ const dataContract = dataContractLike instanceof DataContractWASM
8
+ ? dataContractLike
9
+ : await getDataContractByIdentifier(grpcPool, quorumKeyProvider, dataContractLike);
8
10
  const startIdentifier = startAt ?? startAfter;
9
11
  const startAtIncluded = startAt != null;
10
12
  const request = createDocumentsV1Request({
11
- dataContractId: (new IdentifierWASM(dataContractId)).bytes(),
13
+ dataContractId: dataContract.id.bytes(),
12
14
  documentType: documentTypeName,
13
15
  whereClauses: toWhereClauses(where),
14
16
  orderBy: toOrderClauses(orderBy),
@@ -4,6 +4,11 @@ export interface GRPCOptions {
4
4
  poolLimit?: number;
5
5
  dapiUrl?: string | string[];
6
6
  retries?: number;
7
+ /**
8
+ * Deadline of a single request attempt in milliseconds, the request is aborted and retried on another node when it expires.
9
+ * Streams and long-polling requests are not limited by it. Default is 10 seconds
10
+ */
11
+ requestTimeout?: number;
7
12
  /**
8
13
  * Minimal protocol version of the nodes, nodes with the protocol version from `minProtocolVersion` up to the latest
9
14
  * version supported by the SDK are used. By default, nodes with any protocol version up to the latest one are used.
@@ -59,6 +64,7 @@ export default class GRPCConnectionPool implements GRPCPool {
59
64
  dapiUrls: string[];
60
65
  network: Network;
61
66
  readonly retries: number;
67
+ readonly requestTimeout: number;
62
68
  proofs?: boolean;
63
69
  protocolVersion: number;
64
70
  constructor(network: Network, grpcOptions?: GRPCOptions);
@@ -10,34 +10,21 @@ const GRPC_DEFAULT_CONNECT_RETRIES = 5;
10
10
  // first ban lasts 60 seconds, every next ban without a successful request in between lasts e times longer
11
11
  const NODE_BASE_BAN_PERIOD_MS = 60 * 1000;
12
12
  const RETRY_DELAY_MS = 10;
13
+ const GRPC_DEFAULT_REQUEST_TIMEOUT_MS = 10 * 1000;
13
14
  const seedNodes = {
14
15
  testnet: [
15
16
  // seed-1.pshenmic.dev
16
17
  'https://153.80.206.232:1443',
17
18
  // DCG seed
18
- 'https://34.209.12.72:1443',
19
- // Testnet validators (hp-masternode-1 -> hp-masternode-15)
20
- 'https://68.67.122.1:1443',
21
- 'https://68.67.122.2:1443',
22
- 'https://68.67.122.3:1443',
23
- 'https://68.67.122.4:1443',
24
- 'https://68.67.122.5:1443',
25
- 'https://68.67.122.6:1443',
26
- 'https://68.67.122.7:1443',
27
- 'https://68.67.122.8:1443',
28
- 'https://68.67.122.9:1443',
29
- 'https://68.67.122.10:1443',
30
- 'https://68.67.122.11:1443',
31
- 'https://68.67.122.12:1443',
32
- 'https://68.67.122.13:1443',
33
- 'https://68.67.122.14:1443',
34
- 'https://68.67.122.15:1443'
19
+ 'https://seed-1.testnet.networks.dash.org:1443',
20
+ // Testnet validator
21
+ 'https://68.67.122.1:1443'
35
22
  ],
36
23
  mainnet: [
37
24
  // seed-1.pshenmic.dev
38
25
  'https://153.80.206.97:443',
39
26
  // DCG seed
40
- 'https://34.211.174.194:443',
27
+ 'https://seed-1.mainnet.networks.dash.org:443',
41
28
  // validator
42
29
  'https://95.216.146.18:443'
43
30
  ]
@@ -46,15 +33,17 @@ const DAPI_PORTS = {
46
33
  testnet: 1443,
47
34
  mainnet: 443
48
35
  };
49
- const HEALTHCHECK_TIMEOUT_MS = 5000;
36
+ // Seeds bootstrap the pool without blocking init. Validator discovery runs after the first
37
+ // successful request, so it never competes with the first queries.
38
+ const SEED_DISCOVERY_TIMEOUT_MS = 3000;
39
+ const SEED_DISCOVERY_DELAY_MS = 2500;
40
+ const VALIDATOR_CHECK_TIMEOUT_MS = 5000;
50
41
  // platform produces empty blocks every 3 minutes, so a healthy chain is never older than that
51
- const HEALTHCHECK_MAX_BLOCK_AGE_MS = 10 * 60 * 1000;
52
- // Per-client concurrency × clients initializing at once is the instantaneous load on nodes,
53
- // so healthchecks run a small window at a time to avoid a fleet-wide request burst.
54
- const HEALTHCHECK_CONCURRENCY = 2;
55
- // Init resolves at this many healthy nodes; seeds only bootstrap the pool and are replaced
56
- // by discovered validators, so they never stay in the long-lived pool.
57
- const HEALTHCHECK_MIN_HEALTHY_NODES = 2;
42
+ const VALIDATOR_CHECK_MAX_BLOCK_AGE_MS = 10 * 60 * 1000;
43
+ // The pool keeps serving requests with the seeds until this many validators are healthy.
44
+ const VALIDATOR_CHECK_MIN_HEALTHY = 2;
45
+ // Validators are healthchecked a small window at a time to avoid a request burst.
46
+ const VALIDATOR_CHECK_CONCURRENCY = 2;
58
47
  const isAbortError = (error) => error instanceof Error && error.name === 'AbortError';
59
48
  // errors raised before the request is sent to the node, so it is always safe to send it to another node
60
49
  const CONNECT_ERROR_CODES = ['UND_ERR_CONNECT_TIMEOUT', 'ECONNREFUSED', 'EHOSTUNREACH', 'ENETUNREACH', 'EHOSTDOWN', 'ENETDOWN'];
@@ -82,23 +71,34 @@ export const createClient = (url, abortController, fetch = fetchWithDetails) =>
82
71
  /**
83
72
  * Runs a request with an AbortController that is aborted after the given timeout
84
73
  */
85
- const withTimeout = async (request, timeoutMs = HEALTHCHECK_TIMEOUT_MS) => {
74
+ const withTimeout = async (request, timeoutMs = SEED_DISCOVERY_TIMEOUT_MS) => {
86
75
  const abortController = new AbortController();
87
- const timeout = setTimeout(() => abortController.abort(), timeoutMs);
76
+ let timeout;
88
77
  try {
89
- return await request(abortController);
78
+ // Race with a rejection as well: aborting a fetch is not guaranteed to settle the
79
+ // promise, e.g. while the TLS handshake is stuck, so the timeout must reject explicitly.
80
+ return await Promise.race([
81
+ request(abortController),
82
+ new Promise((_resolve, reject) => {
83
+ timeout = setTimeout(() => {
84
+ abortController.abort();
85
+ reject(new Error(`Request timed out after ${timeoutMs}ms`));
86
+ }, timeoutMs);
87
+ })
88
+ ]);
90
89
  }
91
90
  finally {
92
- clearTimeout(timeout);
91
+ if (timeout != null) {
92
+ clearTimeout(timeout);
93
+ }
93
94
  }
94
95
  };
95
- const isNodeHealthy = async (url, minProtocolVersion, signal) => {
96
+ const isNodeHealthy = async (url, minProtocolVersion) => {
96
97
  try {
97
98
  const response = await withTimeout(async (abortController) => {
98
- signal?.addEventListener('abort', () => abortController.abort());
99
99
  const { response } = await createClient(url, abortController).getStatus(GetStatusRequest.create({}));
100
100
  return response;
101
- });
101
+ }, VALIDATOR_CHECK_TIMEOUT_MS);
102
102
  if (response.version.oneofKind !== 'v0') {
103
103
  return false;
104
104
  }
@@ -119,7 +119,7 @@ const isNodeHealthy = async (url, minProtocolVersion, signal) => {
119
119
  }
120
120
  // chain is stalled, last block is too old relative to the node's own clock
121
121
  // (local time is in seconds, block time is in milliseconds)
122
- if (time?.block == null || Number(time.local) * 1000 - Number(time.block) > HEALTHCHECK_MAX_BLOCK_AGE_MS) {
122
+ if (time?.block == null || Number(time.local) * 1000 - Number(time.block) > VALIDATOR_CHECK_MAX_BLOCK_AGE_MS) {
123
123
  return false;
124
124
  }
125
125
  return true;
@@ -145,10 +145,14 @@ export default class GRPCConnectionPool {
145
145
  #dapiUrl;
146
146
  #minProtocolVersion;
147
147
  retries;
148
+ requestTimeout;
148
149
  proofs;
149
150
  protocolVersion;
150
151
  #nodeIndex = 0;
151
152
  #initialization;
153
+ #discoveryScheduled = false;
154
+ // Known seeds that are not in the active pool yet, used only when the active nodes fail
155
+ #fallbackUrls = [];
152
156
  // ban state of nodes that failed with a retryable error, banned nodes are skipped on node selection
153
157
  #bans = new Map();
154
158
  // node that served (or is serving) the request of the client
@@ -158,6 +162,10 @@ export default class GRPCConnectionPool {
158
162
  if (!Number.isInteger(retries) || retries < 0) {
159
163
  throw new Error(`GRPC retries must be a non-negative integer, got ${String(retries)}`);
160
164
  }
165
+ const requestTimeout = grpcOptions?.requestTimeout ?? GRPC_DEFAULT_REQUEST_TIMEOUT_MS;
166
+ if (!Number.isInteger(requestTimeout) || requestTimeout <= 0) {
167
+ throw new Error(`GRPC requestTimeout must be a positive integer, got ${String(requestTimeout)}`);
168
+ }
161
169
  const minProtocolVersion = grpcOptions?.minProtocolVersion;
162
170
  if (minProtocolVersion != null && (!Number.isInteger(minProtocolVersion) || minProtocolVersion < 1 || minProtocolVersion > Number(LATEST_PLATFORM_VERSION))) {
163
171
  throw new Error(`GRPC minProtocolVersion must be an integer from 1 to ${Number(LATEST_PLATFORM_VERSION)}, got ${String(minProtocolVersion)}`);
@@ -169,6 +177,7 @@ export default class GRPCConnectionPool {
169
177
  this.#poolLimit = grpcOptions?.poolLimit ?? GRPC_DEFAULT_POOL_LIMIT;
170
178
  this.#dapiUrl = grpcOptions?.dapiUrl;
171
179
  this.retries = retries;
180
+ this.requestTimeout = requestTimeout;
172
181
  // start initialization in the background, failures are reported on the first request
173
182
  this.#initialization = this.#initializePool();
174
183
  this.#initialization.catch(() => { });
@@ -186,80 +195,94 @@ export default class GRPCConnectionPool {
186
195
  }
187
196
  return;
188
197
  }
189
- // Race all seeds for discovery; the first successful response wins and the losers are
190
- // aborted. If every seed fails, init rejects with "no peers" (the original contract).
191
- const quorumsInfoPromise = async () => {
192
- const winner = new AbortController();
193
- try {
194
- return await Promise.any(seedNodes[network].map(async (seed) => await withTimeout(async (abortController) => {
195
- winner.signal.addEventListener('abort', () => abortController.abort());
196
- return await getCurrentQuorumsInfo({ network, getClient: () => createClient(seed, abortController) });
197
- })));
198
- }
199
- catch (e) {
200
- const errors = e.errors;
201
- throw new AggregateError(errors, `None of the ${network} seed nodes are available: ${errors.map(String).join('; ')}`);
202
- }
203
- finally {
204
- winner.abort();
205
- }
206
- };
207
- // Bootstrap the pool by racing all seed healthchecks; resolve at the first K healthy
208
- // and abort the rest, so a slow/dead seed never stalls initialization.
209
- const seeds = seedNodes[network];
210
- const healthySeeds = [];
211
- const bootstrapPromise = new Promise((resolve, reject) => {
212
- const race = new AbortController();
213
- let pending = seeds.length;
214
- seeds.forEach(seed => {
215
- void isNodeHealthy(seed, this.#minProtocolVersion, race.signal).then(healthy => {
216
- if (healthy) {
217
- healthySeeds.push(seed);
218
- if (healthySeeds.length >= HEALTHCHECK_MIN_HEALTHY_NODES) {
219
- race.abort();
220
- resolve();
221
- }
222
- }
223
- pending -= 1;
224
- if (pending === 0) {
225
- if (healthySeeds.length === 0) {
226
- reject(new Error(`None of the ${network} seed nodes are available ` +
227
- `(nodes must be synced and run protocol version ${this.#minProtocolVersion ?? 1}-${Number(LATEST_PLATFORM_VERSION)})`));
228
- }
229
- else {
230
- resolve();
231
- }
232
- }
233
- });
198
+ // The first request is the healthcheck: start from the primary seed, keep the rest as
199
+ // fallbacks for retries, and promote healthy ones in the background.
200
+ const seeds = [seedNodes[network][0], ...shuffle(seedNodes[network].slice(1))];
201
+ this.dapiUrls = [seeds[0]];
202
+ this.#fallbackUrls = seeds.slice(1);
203
+ this.#probeFallbacks();
204
+ }
205
+ /**
206
+ * Healthchecks the fallback seeds in the background and promotes the healthy ones.
207
+ * An unhealthy seed stays in the fallback list, so a request retry can still try it.
208
+ */
209
+ #probeFallbacks() {
210
+ for (const url of [...this.#fallbackUrls]) {
211
+ void isNodeHealthy(url, this.#minProtocolVersion).then(healthy => {
212
+ if (healthy) {
213
+ this.#promoteFallback(url);
214
+ }
234
215
  });
235
- });
236
- // Discovery failure fails initialization with "no peers", exactly as before.
237
- const [, quorumsInfo] = await Promise.all([bootstrapPromise, quorumsInfoPromise()]);
238
- this.dapiUrls = [...healthySeeds];
239
- // Replace the bootstrap seeds with discovered validators in the background.
240
- void (async () => {
241
- const validators = shuffle([...new Set(quorumsInfo.validatorSets
242
- .flatMap(validatorSet => validatorSet.members)
243
- .filter(member => !member.isBanned)
244
- .map(member => `https://${member.nodeIp}:${DAPI_PORTS[network]}`))]);
245
- const healthyValidators = [];
246
- let validatorIndex = 0;
247
- const checkValidator = async () => {
248
- while (validatorIndex < validators.length && healthyValidators.length < this.#poolLimit) {
249
- const url = validators[validatorIndex++];
250
- if (await isNodeHealthy(url, this.#minProtocolVersion)) {
251
- healthyValidators.push(url);
252
- // Evict the bootstrap seeds once enough validators are healthy.
253
- if (healthyValidators.length >= HEALTHCHECK_MIN_HEALTHY_NODES) {
254
- this.dapiUrls = healthyValidators.slice(0, this.#poolLimit);
255
- }
216
+ }
217
+ }
218
+ #promoteFallback(url) {
219
+ if (!this.#fallbackUrls.includes(url)) {
220
+ return;
221
+ }
222
+ this.#fallbackUrls = this.#fallbackUrls.filter(fallback => fallback !== url);
223
+ this.dapiUrls.push(url);
224
+ }
225
+ /**
226
+ * Starts validator discovery once, after the first request had a chance to complete.
227
+ * It is a background job: the pool keeps serving requests from the seeds meanwhile.
228
+ */
229
+ #scheduleDiscovery() {
230
+ if (this.#discoveryScheduled || this.#dapiUrl != null) {
231
+ return;
232
+ }
233
+ this.#discoveryScheduled = true;
234
+ setTimeout(() => {
235
+ void this.#discoverValidators().catch(() => {
236
+ // keep using the seeds if discovery fails
237
+ });
238
+ }, SEED_DISCOVERY_DELAY_MS);
239
+ }
240
+ /**
241
+ * Fetches the current validator set, healthchecks its nodes and replaces the seeds with
242
+ * the healthy validators. The checks run here, off the critical path, so the first requests
243
+ * are never delayed by them and the long-lived pool does not fill up with lagging nodes.
244
+ */
245
+ async #discoverValidators() {
246
+ const { network } = this;
247
+ const quorumsInfo = await this.#fetchQuorumsInfo();
248
+ const validators = shuffle([...new Set(quorumsInfo.validatorSets
249
+ .flatMap(validatorSet => validatorSet.members)
250
+ .filter(member => !member.isBanned)
251
+ .map(member => `https://${member.nodeIp}:${DAPI_PORTS[network]}`))]);
252
+ if (validators.length === 0) {
253
+ return;
254
+ }
255
+ const healthyValidators = [];
256
+ let validatorIndex = 0;
257
+ const checkValidator = async () => {
258
+ while (validatorIndex < validators.length && healthyValidators.length < this.#poolLimit) {
259
+ const url = validators[validatorIndex++];
260
+ if (await isNodeHealthy(url, this.#minProtocolVersion)) {
261
+ healthyValidators.push(url);
262
+ // Replace the seeds once enough validators are healthy, so a single slow node
263
+ // cannot hold the whole pool. Otherwise the seeds stay as a fallback.
264
+ if (healthyValidators.length >= VALIDATOR_CHECK_MIN_HEALTHY) {
265
+ this.dapiUrls = healthyValidators.slice(0, this.#poolLimit);
256
266
  }
257
267
  }
258
- };
259
- await Promise.all(Array.from({ length: HEALTHCHECK_CONCURRENCY }, async () => await checkValidator()));
260
- })().catch(() => {
261
- // keep the bootstrap seeds if validator discovery or healthchecks fail
262
- });
268
+ }
269
+ };
270
+ await Promise.all(Array.from({ length: VALIDATOR_CHECK_CONCURRENCY }, async () => await checkValidator()));
271
+ }
272
+ /**
273
+ * Reads the current quorums info from the first responding seed.
274
+ */
275
+ async #fetchQuorumsInfo() {
276
+ const winner = new AbortController();
277
+ try {
278
+ return await Promise.any(shuffle([...seedNodes[this.network]]).map(async (seed) => await withTimeout(async (abortController) => {
279
+ winner.signal.addEventListener('abort', () => abortController.abort());
280
+ return await getCurrentQuorumsInfo({ network: this.network, getClient: () => createClient(seed, abortController) });
281
+ })));
282
+ }
283
+ finally {
284
+ winner.abort();
285
+ }
263
286
  }
264
287
  /**
265
288
  * Waits for the pool initialization and returns a client connected to the next healthy node (round-robin)
@@ -311,7 +334,7 @@ export default class GRPCConnectionPool {
311
334
  }
312
335
  #ban(url) {
313
336
  // a single node is never banned, otherwise the pool would have no nodes to send requests to
314
- if (this.dapiUrls.length <= 1) {
337
+ if (this.dapiUrls.length + this.#fallbackUrls.length <= 1) {
315
338
  return;
316
339
  }
317
340
  const bannedTimes = this.#bans.get(url)?.bannedTimes ?? 0;
@@ -336,6 +359,13 @@ export default class GRPCConnectionPool {
336
359
  return url;
337
360
  }
338
361
  }
362
+ // Every active node is banned or already tried: promote a fallback seed into the pool.
363
+ // This keeps the first batch on the primary node while preserving failover.
364
+ const fallback = this.#fallbackUrls.find(url => !exclude.includes(url) && !this.#isBanned(url));
365
+ if (fallback != null) {
366
+ this.#promoteFallback(fallback);
367
+ return fallback;
368
+ }
339
369
  return undefined;
340
370
  }
341
371
  /**
@@ -347,32 +377,62 @@ export default class GRPCConnectionPool {
347
377
  return async (input, init) => {
348
378
  // transport always requests `${dapiUrl}/${service}/${method}`
349
379
  const methodPath = String(input).slice(dapiUrl.length);
380
+ // streams and long-polls wait for the node as long as it takes and are aborted only by the caller's signal
381
+ const hasDeadline = !methodPath.includes('subscribe') && !methodPath.includes('waitForStateTransitionResult');
382
+ const outerSignal = init?.signal;
350
383
  const triedUrls = [dapiUrl];
351
384
  let nodeUrl = dapiUrl;
352
385
  for (let retry = 0;; retry++) {
386
+ const abortController = hasDeadline ? new AbortController() : undefined;
387
+ const onOuterAbort = () => abortController?.abort();
388
+ const timeout = hasDeadline ? setTimeout(() => abortController?.abort(), this.requestTimeout) : undefined;
389
+ if (abortController != null) {
390
+ outerSignal?.addEventListener('abort', onOuterAbort);
391
+ if (outerSignal?.aborted === true) {
392
+ abortController.abort();
393
+ }
394
+ }
353
395
  try {
354
- return await fetchWithDetails(`${nodeUrl}${methodPath}`, init);
396
+ const response = await fetchWithDetails(`${nodeUrl}${methodPath}`, abortController != null ? { ...init, signal: abortController.signal } : init);
397
+ // a successful request resets the ban escalation of the node
398
+ this.#bans.delete(nodeUrl);
399
+ // The first served request doubles as the seed healthcheck; start the
400
+ // background validator discovery only after it succeeded.
401
+ this.#scheduleDiscovery();
402
+ return response;
355
403
  }
356
404
  catch (e) {
405
+ // the deadline abort is retryable, the caller's abort is not
406
+ const timedOut = abortController?.signal.aborted === true && outerSignal?.aborted !== true;
407
+ // surface the expired deadline as a timeout error instead of a bare abort
408
+ const error = timedOut
409
+ ? Object.assign(new Error(`Request timed out after ${this.requestTimeout}ms`, { cause: e }), { name: 'TimeoutError' })
410
+ : e;
357
411
  // state transition could already be received by the node,
358
412
  // so broadcast is retried only if the connection was not established
359
- const isRetryable = methodPath.includes('broadcast') ? isConnectError(e) : !isAbortError(e);
360
- if (!isRetryable || init?.signal?.aborted === true) {
361
- throw e;
413
+ const isRetryable = methodPath.includes('broadcast') ? isConnectError(e) : (!isAbortError(e) || timedOut);
414
+ if (!isRetryable || outerSignal?.aborted === true) {
415
+ throw error;
362
416
  }
363
417
  this.#ban(nodeUrl);
364
418
  if (retry >= this.retries) {
365
- throw e;
419
+ throw error;
366
420
  }
367
421
  await sleep(RETRY_DELAY_MS);
368
- const nextUrl = init?.signal?.aborted !== true ? this.#nextNode(triedUrls) : undefined;
422
+ const nextUrl = outerSignal?.aborted !== true ? this.#nextNode(triedUrls) : undefined;
369
423
  if (nextUrl == null) {
370
- throw e;
424
+ throw error;
371
425
  }
372
426
  triedUrls.push(nextUrl);
373
427
  nodeUrl = nextUrl;
374
428
  onNodeChange(nextUrl);
375
429
  }
430
+ finally {
431
+ clearTimeout(timeout);
432
+ if (abortController != null) {
433
+ outerSignal?.removeEventListener('abort', onOuterAbort);
434
+ }
435
+ }
376
436
  }
377
437
  };
378
438
  }
@@ -11,6 +11,7 @@ export declare class NamesController {
11
11
  grpcPool: GRPCPool;
12
12
  /** @ignore **/
13
13
  quorumKeyProvider: QuorumKeyProvider;
14
+ private dataContract;
14
15
  constructor(grpcPool: GRPCPool, quorumKeyProvider: QuorumKeyProvider);
15
16
  /**
16
17
  * Searches for a registered DPNS name in the network
@@ -71,4 +72,5 @@ export declare class NamesController {
71
72
  * @return {string} null if valid or string with a reason
72
73
  */
73
74
  validateName(fullName: string): null | string;
75
+ private getDataContract;
74
76
  }
@@ -6,6 +6,8 @@ import validateName from './validateName.js';
6
6
  import getIdentityByIdentifier from '../identities/getIdentityByIdentifier.js';
7
7
  import convertToHomographSafeChars from '../utils/convertToHomographSafeChars.js';
8
8
  import testNameContested from './testNameContested.js';
9
+ import getDataContractByIdentifier from '../dataContracts/getDataContractByIdentifier.js';
10
+ import { DPNS_DATA_CONTRACT_ID } from "../constants.js";
9
11
  /**
10
12
  * Functions related to DPNS names (usernames)
11
13
  *
@@ -16,6 +18,7 @@ export class NamesController {
16
18
  grpcPool;
17
19
  /** @ignore **/
18
20
  quorumKeyProvider;
21
+ dataContract;
19
22
  constructor(grpcPool, quorumKeyProvider) {
20
23
  this.grpcPool = grpcPool;
21
24
  this.quorumKeyProvider = quorumKeyProvider;
@@ -39,7 +42,8 @@ export class NamesController {
39
42
  if (validation != null) {
40
43
  throw new Error(validation);
41
44
  }
42
- return await searchByName(this.grpcPool, this.quorumKeyProvider, name);
45
+ const contract = await this.getDataContract();
46
+ return await searchByName(this.grpcPool, this.quorumKeyProvider, name, contract);
43
47
  }
44
48
  /**
45
49
  * Tests a given username against contested names rules.
@@ -60,7 +64,8 @@ export class NamesController {
60
64
  return testNameContested(normalizedLabel);
61
65
  }
62
66
  async searchByIdentity(identifier) {
63
- return await searchByIdentity(this.grpcPool, this.quorumKeyProvider, new IdentifierWASM(identifier));
67
+ const contract = await this.getDataContract();
68
+ return await searchByIdentity(this.grpcPool, this.quorumKeyProvider, new IdentifierWASM(identifier), contract);
64
69
  }
65
70
  /**
66
71
  * Performs a DPNS name registration sequence
@@ -106,4 +111,10 @@ export class NamesController {
106
111
  validateName(fullName) {
107
112
  return validateName(fullName);
108
113
  }
114
+ async getDataContract() {
115
+ if (this.dataContract == null) {
116
+ this.dataContract = await getDataContractByIdentifier(this.grpcPool, this.quorumKeyProvider, DPNS_DATA_CONTRACT_ID);
117
+ }
118
+ return this.dataContract;
119
+ }
109
120
  }
@@ -1,4 +1,4 @@
1
- import { DocumentWASM, IdentifierWASM } from 'pshenmic-dpp';
1
+ import { DataContractWASM, DocumentWASM, IdentifierLike, IdentifierWASM } from 'pshenmic-dpp';
2
2
  import { GRPCPool } from '../grpcConnectionPool.js';
3
3
  import { QuorumKeyProvider } from '../quorumKeyProvider.js';
4
- export default function searchByIdentity(grpcPool: GRPCPool, quorumKeyProvider: QuorumKeyProvider, identifier: IdentifierWASM): Promise<DocumentWASM[]>;
4
+ export default function searchByIdentity(grpcPool: GRPCPool, quorumKeyProvider: QuorumKeyProvider, identifier: IdentifierWASM, contract: IdentifierLike | DataContractWASM): Promise<DocumentWASM[]>;
@@ -1,5 +1,4 @@
1
1
  import query from '../documents/query.js';
2
- const DPNS_DATA_CONTRACT_ID = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec';
3
- export default async function searchByIdentity(grpcPool, quorumKeyProvider, identifier) {
4
- return await query(grpcPool, quorumKeyProvider, DPNS_DATA_CONTRACT_ID, 'domain', [['records.identity', '=', identifier.base58()]], [['records.identity', 'asc']]);
2
+ export default async function searchByIdentity(grpcPool, quorumKeyProvider, identifier, contract) {
3
+ return await query(grpcPool, quorumKeyProvider, contract, 'domain', [['records.identity', '=', identifier.base58()]], [['records.identity', 'asc']]);
5
4
  }