dash-platform-sdk 1.6.0-dev.1 → 1.6.0-dev.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/README.md +33 -15
  2. package/bundle.min.js +1 -1
  3. package/index.d.ts +3 -1
  4. package/index.js +2 -1
  5. package/package.json +2 -2
  6. package/proto/generated/platform.d.ts +128 -2
  7. package/proto/generated/platform.js +266 -8
  8. package/src/DashPlatformSDK.d.ts +19 -1
  9. package/src/DashPlatformSDK.js +28 -10
  10. package/src/QueryExecutor.d.ts +122 -0
  11. package/src/QueryExecutor.js +205 -0
  12. package/src/constants.d.ts +6 -0
  13. package/src/constants.js +6 -0
  14. package/src/contestedResources/getContestedResourceVoteState.d.ts +2 -1
  15. package/src/contestedResources/getContestedResourceVoteState.js +69 -49
  16. package/src/contestedResources/index.d.ts +4 -1
  17. package/src/contestedResources/index.js +5 -2
  18. package/src/dataContracts/getDataContractByIdentifier.d.ts +2 -1
  19. package/src/dataContracts/getDataContractByIdentifier.js +15 -27
  20. package/src/dataContracts/index.d.ts +4 -1
  21. package/src/dataContracts/index.js +5 -2
  22. package/src/documents/create.d.ts +1 -1
  23. package/src/documents/create.js +2 -2
  24. package/src/documents/getActionFeeAgreement.d.ts +2 -1
  25. package/src/documents/getActionFeeAgreement.js +3 -3
  26. package/src/documents/index.d.ts +14 -9
  27. package/src/documents/index.js +19 -15
  28. package/src/documents/query.d.ts +2 -1
  29. package/src/documents/query.js +16 -8
  30. package/src/documents/queryAggregate.d.ts +8 -1
  31. package/src/documents/queryAggregate.js +49 -15
  32. package/src/documents/queryJoined.d.ts +3 -2
  33. package/src/documents/queryJoined.js +54 -13
  34. package/src/documents/queryRanked.d.ts +3 -2
  35. package/src/documents/queryRanked.js +49 -15
  36. package/src/documents/v1.d.ts +25 -8
  37. package/src/documents/v1.js +50 -14
  38. package/src/grpcConnectionPool.d.ts +24 -4
  39. package/src/grpcConnectionPool.js +153 -37
  40. package/src/identities/getIdentityBalance.d.ts +2 -1
  41. package/src/identities/getIdentityBalance.js +13 -27
  42. package/src/identities/getIdentityByIdentifier.d.ts +2 -1
  43. package/src/identities/getIdentityByIdentifier.js +14 -28
  44. package/src/identities/getIdentityByNonUniquePublicKeyHash.d.ts +2 -1
  45. package/src/identities/getIdentityByNonUniquePublicKeyHash.js +49 -28
  46. package/src/identities/getIdentityByPublicKeyHash.d.ts +2 -1
  47. package/src/identities/getIdentityByPublicKeyHash.js +14 -28
  48. package/src/identities/getIdentityContractNonce.d.ts +2 -1
  49. package/src/identities/getIdentityContractNonce.js +10 -27
  50. package/src/identities/getIdentityNonce.d.ts +2 -1
  51. package/src/identities/getIdentityNonce.js +10 -27
  52. package/src/identities/getIdentityPublicKeys.d.ts +2 -1
  53. package/src/identities/getIdentityPublicKeys.js +16 -29
  54. package/src/identities/index.d.ts +4 -1
  55. package/src/identities/index.js +11 -8
  56. package/src/names/index.d.ts +8 -2
  57. package/src/names/index.js +12 -6
  58. package/src/names/registerName.d.ts +2 -1
  59. package/src/names/registerName.js +56 -36
  60. package/src/names/searchByIdentity.d.ts +2 -1
  61. package/src/names/searchByIdentity.js +2 -2
  62. package/src/names/searchByName.d.ts +2 -1
  63. package/src/names/searchByName.js +2 -2
  64. package/src/node/epochInfos.d.ts +2 -1
  65. package/src/node/epochInfos.js +27 -31
  66. package/src/node/finalizedEpochInfos.d.ts +4 -3
  67. package/src/node/finalizedEpochInfos.js +45 -39
  68. package/src/node/index.d.ts +4 -1
  69. package/src/node/index.js +7 -4
  70. package/src/node/totalCredits.d.ts +2 -1
  71. package/src/node/totalCredits.js +10 -25
  72. package/src/platformAddresses/getAddressInfo.d.ts +2 -1
  73. package/src/platformAddresses/getAddressInfo.js +17 -31
  74. package/src/platformAddresses/getAddressesBranchState.d.ts +2 -1
  75. package/src/platformAddresses/getAddressesBranchState.js +22 -8
  76. package/src/platformAddresses/getAddressesInfos.d.ts +2 -1
  77. package/src/platformAddresses/getAddressesInfos.js +18 -29
  78. package/src/platformAddresses/getAddressesTrunkState.d.ts +2 -1
  79. package/src/platformAddresses/getAddressesTrunkState.js +25 -23
  80. package/src/platformAddresses/getRecentAddressBalanceChanges.d.ts +2 -1
  81. package/src/platformAddresses/getRecentAddressBalanceChanges.js +26 -26
  82. package/src/platformAddresses/getRecentCompactedAddressBalanceChanges.d.ts +2 -1
  83. package/src/platformAddresses/getRecentCompactedAddressBalanceChanges.js +30 -26
  84. package/src/platformAddresses/index.d.ts +4 -1
  85. package/src/platformAddresses/index.js +10 -7
  86. package/src/quorumKeyProvider.d.ts +23 -0
  87. package/src/quorumKeyProvider.js +28 -0
  88. package/src/shielded/getMostRecentShieldedAnchor.d.ts +2 -1
  89. package/src/shielded/getMostRecentShieldedAnchor.js +8 -25
  90. package/src/shielded/getShieldedAnchors.d.ts +2 -1
  91. package/src/shielded/getShieldedAnchors.js +8 -25
  92. package/src/shielded/getShieldedEncryptedNotes.d.ts +2 -1
  93. package/src/shielded/getShieldedEncryptedNotes.js +16 -30
  94. package/src/shielded/getShieldedNotesCount.d.ts +2 -1
  95. package/src/shielded/getShieldedNotesCount.js +8 -25
  96. package/src/shielded/getShieldedNullifiers.d.ts +2 -1
  97. package/src/shielded/getShieldedNullifiers.js +14 -28
  98. package/src/shielded/getShieldedPoolState.d.ts +2 -1
  99. package/src/shielded/getShieldedPoolState.js +8 -25
  100. package/src/shielded/index.d.ts +4 -1
  101. package/src/shielded/index.js +10 -7
  102. package/src/stateTransitions/index.d.ts +4 -1
  103. package/src/stateTransitions/index.js +5 -2
  104. package/src/stateTransitions/waitForStateTransitionResult.d.ts +2 -1
  105. package/src/stateTransitions/waitForStateTransitionResult.js +42 -44
  106. package/src/tokens/getIdentitiesTokenBalances.d.ts +2 -1
  107. package/src/tokens/getIdentitiesTokenBalances.js +17 -28
  108. package/src/tokens/getIdentityTokensBalances.d.ts +2 -1
  109. package/src/tokens/getIdentityTokensBalances.js +17 -28
  110. package/src/tokens/getTokenContractInfo.d.ts +2 -1
  111. package/src/tokens/getTokenContractInfo.js +16 -30
  112. package/src/tokens/getTokenDirectPurchasePrices.d.ts +2 -1
  113. package/src/tokens/getTokenDirectPurchasePrices.js +26 -28
  114. package/src/tokens/getTokenTotalSupply.d.ts +2 -1
  115. package/src/tokens/getTokenTotalSupply.js +16 -28
  116. package/src/tokens/index.d.ts +4 -1
  117. package/src/tokens/index.js +11 -8
  118. package/src/utils/ProofError.d.ts +9 -0
  119. package/src/utils/ProofError.js +10 -0
  120. package/src/utils/verifyTenderdashProof.js +2 -1
  121. package/test/unit/Document.spec.js +9 -9
  122. package/test/unit/DocumentActionFees.spec.js +2 -2
  123. package/test/unit/Names.spec.js +30 -0
  124. package/test/unit/Node.spec.js +11 -8
  125. package/test/unit/SDK.spec.js +42 -0
  126. package/src/utils/getQuorumPublicKey.d.ts +0 -1
  127. package/src/utils/getQuorumPublicKey.js +0 -19
@@ -1,9 +1,31 @@
1
1
  import { IdentifierWASM, verifyHavingDocumentsProof, verifyRankedDocumentsProof } from 'pshenmic-dpp';
2
2
  import { LATEST_PLATFORM_VERSION } from '../constants.js';
3
3
  import getDataContractByIdentifier from '../dataContracts/getDataContractByIdentifier.js';
4
- import { getDocumentsV1Proof, toHavingClauses, toOrderClauses, toSelect, toWhereClauses, verifyDocumentsV1Signature } from './v1.js';
5
- async function getRankedProof(grpcPool, dataContractId, query, having) {
6
- return await getDocumentsV1Proof(grpcPool, {
4
+ import QueryExecutor from '../QueryExecutor.js';
5
+ import { createDocumentsV1Request, getDocumentsV1Data, getDocumentsV1Proof, toHavingClauses, toOrderClauses, toSelect, toWhereClauses } from './v1.js';
6
+ // average of the proof verification is a fixed point number scaled by 10^19
7
+ const AVG_FIXED_POINT_SCALE = 1e19;
8
+ /**
9
+ * Converts the ranked entries of a response requested without proof to the ones of the proof verification
10
+ */
11
+ function toRankedEntries(entries) {
12
+ return entries.map(({ key, inKey, value }) => {
13
+ let rankedValue = {};
14
+ if (value.oneofKind === 'count') {
15
+ rankedValue = { count: BigInt(value.count) };
16
+ }
17
+ else if (value.oneofKind === 'sum') {
18
+ rankedValue = { sum: BigInt(value.sum) };
19
+ }
20
+ else if (value.oneofKind === 'avg') {
21
+ // average is returned as a double without proof, so its precision is limited
22
+ rankedValue = { avgFixedPoint: BigInt(Math.round(value.avg * AVG_FIXED_POINT_SCALE)) };
23
+ }
24
+ return { key, inKey: inKey ?? null, value: rankedValue };
25
+ });
26
+ }
27
+ function createRankedRequest(dataContractId, query, having) {
28
+ return createDocumentsV1Request({
7
29
  dataContractId: (new IdentifierWASM(dataContractId)).bytes(),
8
30
  documentType: query.documentTypeName,
9
31
  whereClauses: toWhereClauses(query.where),
@@ -18,20 +40,32 @@ async function getRankedProof(grpcPool, dataContractId, query, having) {
18
40
  /**
19
41
  * Top-K query: groups of `groupBy` ranked by the selected aggregate in the order `orderBy` names
20
42
  */
21
- export async function queryRanked(grpcPool, dataContractId, query) {
22
- const dataContract = await getDataContractByIdentifier(grpcPool, dataContractId);
23
- const { proof, metadata } = await getRankedProof(grpcPool, dataContractId, query, []);
24
- const { rootHash, value } = verifyRankedDocumentsProof(proof.grovedbProof, dataContract, query, LATEST_PLATFORM_VERSION, BigInt(metadata.timeMs));
25
- await verifyDocumentsV1Signature(grpcPool, proof, metadata, rootHash);
26
- return value;
43
+ export async function queryRanked(grpcPool, quorumKeyProvider, dataContractId, query) {
44
+ const dataContract = await getDataContractByIdentifier(grpcPool, quorumKeyProvider, dataContractId);
45
+ const request = createRankedRequest(dataContractId, query, []);
46
+ return await QueryExecutor.build(grpcPool, quorumKeyProvider)
47
+ .setGrpcRequest('getDocuments', request)
48
+ .mapProof(getDocumentsV1Proof)
49
+ .setProofVerifier(verifyRankedDocumentsProof, ({ metadata }) => [dataContract, query, LATEST_PLATFORM_VERSION, BigInt(metadata.timeMs)])
50
+ .mapResponse(data => {
51
+ if (data.proved) {
52
+ return data.verified.value;
53
+ }
54
+ const { entries, skipped } = getDocumentsV1Data(data.result, 'ranked');
55
+ return { skipped: BigInt(skipped ?? 0), entries: toRankedEntries(entries) };
56
+ })
57
+ .execute();
27
58
  }
28
59
  /**
29
60
  * Having query: groups of `groupBy` whose aggregate falls within the `having` bounds
30
61
  */
31
- export async function queryHaving(grpcPool, dataContractId, query) {
32
- const dataContract = await getDataContractByIdentifier(grpcPool, dataContractId);
33
- const { proof, metadata } = await getRankedProof(grpcPool, dataContractId, query, query.having);
34
- const { rootHash, value } = verifyHavingDocumentsProof(proof.grovedbProof, dataContract, query, LATEST_PLATFORM_VERSION, BigInt(metadata.timeMs));
35
- await verifyDocumentsV1Signature(grpcPool, proof, metadata, rootHash);
36
- return value;
62
+ export async function queryHaving(grpcPool, quorumKeyProvider, dataContractId, query) {
63
+ const dataContract = await getDataContractByIdentifier(grpcPool, quorumKeyProvider, dataContractId);
64
+ const request = createRankedRequest(dataContractId, query, query.having);
65
+ return await QueryExecutor.build(grpcPool, quorumKeyProvider)
66
+ .setGrpcRequest('getDocuments', request)
67
+ .mapProof(getDocumentsV1Proof)
68
+ .setProofVerifier(verifyHavingDocumentsProof, ({ metadata }) => [dataContract, query, LATEST_PLATFORM_VERSION, BigInt(metadata.timeMs)])
69
+ .mapResponse(data => data.proved ? data.verified.value : toRankedEntries(getDocumentsV1Data(data.result, 'ranked').entries))
70
+ .execute();
37
71
  }
@@ -1,6 +1,6 @@
1
- import { GetDocumentsRequest_DocumentFieldValue, GetDocumentsRequest_GetDocumentsRequestV1, GetDocumentsRequest_GetDocumentsRequestV1_SubQuery, GetDocumentsRequest_HavingClause, GetDocumentsRequest_OrderClause, GetDocumentsRequest_WhereClause, Proof, ResponseMetadata } from '../../proto/generated/platform.js';
2
- import { AggregateSelect, CompositeSubQuery, HavingClause, IdentifierLike, IdentifierWASM, WhereClause } from 'pshenmic-dpp';
3
- import { GRPCPool } from '../grpcConnectionPool.js';
1
+ import { GetDocumentsRequest, GetDocumentsRequest_DocumentFieldValue, GetDocumentsRequest_GetDocumentsRequestV1, GetDocumentsRequest_GetDocumentsRequestV1_SubQuery, GetDocumentsRequest_HavingClause, GetDocumentsRequest_OrderClause, GetDocumentsRequest_WhereClause, GetContractDocumentRemovalsResponse_ContractDocumentRemoval, GetDocumentsResponse, GetDocumentsResponse_GetDocumentsResponseV1_ResultData, Proof, ResponseMetadata } from '../../proto/generated/platform.js';
2
+ import { AggregateSelect, CompositeSubQuery, DataContractWASM, DocumentWASM, HavingClause, IdentifierLike, IdentifierWASM, ProvenDocumentRemovalEntry, WhereClause } from 'pshenmic-dpp';
3
+ import { ResponseResult } from '../QueryExecutor.js';
4
4
  type DocumentFieldValue = GetDocumentsRequest_DocumentFieldValue;
5
5
  /**
6
6
  * Converts a JS value of a where / having clause into a typed v1 document field value
@@ -20,14 +20,31 @@ export declare function toHavingClauses(having: HavingClause[]): GetDocumentsReq
20
20
  export declare function toSubQueries(subQueries: CompositeSubQuery[], dataContractId: IdentifierWASM): GetDocumentsRequest_GetDocumentsRequestV1_SubQuery[];
21
21
  export declare function toStart(startAt?: IdentifierLike | null, startAtIncluded?: boolean): GetDocumentsRequest_GetDocumentsRequestV1['start'];
22
22
  /**
23
- * Sends a v1 getDocuments request with a proof and returns the proof with the response metadata
23
+ * Creates a v1 getDocuments request with a proof
24
24
  */
25
- export declare function getDocumentsV1Proof(grpcPool: GRPCPool, v1: Partial<GetDocumentsRequest_GetDocumentsRequestV1>): Promise<{
25
+ export declare function createDocumentsV1Request(v1: Partial<GetDocumentsRequest_GetDocumentsRequestV1>): GetDocumentsRequest;
26
+ /**
27
+ * Returns the proof and the metadata of a v1 getDocuments response
28
+ */
29
+ export declare function getDocumentsV1Proof(response: GetDocumentsResponse): {
26
30
  proof: Proof;
27
31
  metadata: ResponseMetadata;
28
- }>;
32
+ };
33
+ type DocumentsV1Variant = GetDocumentsResponse_GetDocumentsResponseV1_ResultData['variant'];
34
+ type DocumentsV1Kind = NonNullable<DocumentsV1Variant['oneofKind']>;
35
+ type DocumentsV1Data<K extends DocumentsV1Kind> = Extract<DocumentsV1Variant, {
36
+ oneofKind: K;
37
+ }> extends infer V ? V[K & keyof V] : never;
38
+ /**
39
+ * Returns the data of the given kind from the result of a v1 getDocuments response requested without proof
40
+ */
41
+ export declare function getDocumentsV1Data<K extends DocumentsV1Kind>(result: ResponseResult<GetDocumentsResponse>, kind: K): DocumentsV1Data<K>;
42
+ /**
43
+ * Deserializes the documents of a getDocuments response requested without proof
44
+ */
45
+ export declare function toDocuments(documents: Uint8Array[], dataContract: DataContractWASM, documentTypeName: string): DocumentWASM[];
29
46
  /**
30
- * Verifies the quorum signature of a proof whose GroveDB part produced the given root hash
47
+ * Converts the document removal of a getDocuments response requested without proof to the one of the proof verification
31
48
  */
32
- export declare function verifyDocumentsV1Signature(grpcPool: GRPCPool, proof: Proof, metadata: ResponseMetadata, rootHash: Uint8Array): Promise<void>;
49
+ export declare function toDocumentRemovalEntry(removal: GetContractDocumentRemovalsResponse_ContractDocumentRemoval): ProvenDocumentRemovalEntry;
33
50
  export {};
@@ -1,8 +1,6 @@
1
1
  import { GetDocumentsRequest, GetDocumentsRequest_GetDocumentsRequestV1, GetDocumentsRequest_GetDocumentsRequestV1_Select_Function, GetDocumentsRequest_GetDocumentsRequestV1_SubQuery_Kind, GetDocumentsRequest_HavingAggregate_Function, GetDocumentsRequest_HavingClause_Operator, GetDocumentsRequest_IntegerRangeSelection, GetDocumentsRequest_TimeRangeSelection, GetDocumentsRequest_TimeRangeSelection_Selector, GetDocumentsRequest_WhereClause, GetDocumentsRequest_WhereOperator } from '../../proto/generated/platform.js';
2
- import { IdentifierWASM } from 'pshenmic-dpp';
3
- import { getQuorumPublicKey } from '../utils/getQuorumPublicKey.js';
4
- import bytesToHex from '../utils/bytesToHex.js';
5
- import verifyTenderdashProof from '../utils/verifyTenderdashProof.js';
2
+ import { DocumentWASM, IdentifierWASM } from 'pshenmic-dpp';
3
+ import { LATEST_PLATFORM_VERSION } from '../constants.js';
6
4
  const WHERE_OPERATORS = {
7
5
  '=': GetDocumentsRequest_WhereOperator.EQUAL,
8
6
  '==': GetDocumentsRequest_WhereOperator.EQUAL,
@@ -198,16 +196,20 @@ export function toStart(startAt, startAtIncluded) {
198
196
  : { oneofKind: 'startAt', startAt: bytes };
199
197
  }
200
198
  /**
201
- * Sends a v1 getDocuments request with a proof and returns the proof with the response metadata
199
+ * Creates a v1 getDocuments request with a proof
202
200
  */
203
- export async function getDocumentsV1Proof(grpcPool, v1) {
204
- const getDocumentsRequest = GetDocumentsRequest.create({
201
+ export function createDocumentsV1Request(v1) {
202
+ return GetDocumentsRequest.create({
205
203
  version: {
206
204
  oneofKind: 'v1',
207
205
  v1: GetDocumentsRequest_GetDocumentsRequestV1.create({ ...v1, prove: true })
208
206
  }
209
207
  });
210
- const { response } = await (await grpcPool.getClient()).getDocuments(getDocumentsRequest);
208
+ }
209
+ /**
210
+ * Returns the proof and the metadata of a v1 getDocuments response
211
+ */
212
+ export function getDocumentsV1Proof(response) {
211
213
  const { version } = response;
212
214
  if (version.oneofKind !== 'v1') {
213
215
  throw new Error('Unexpected oneOf type returned from DAPI (must be v1)');
@@ -222,12 +224,46 @@ export async function getDocumentsV1Proof(grpcPool, v1) {
222
224
  return { proof: result.proof, metadata };
223
225
  }
224
226
  /**
225
- * Verifies the quorum signature of a proof whose GroveDB part produced the given root hash
227
+ * Returns the data of the given kind from the result of a v1 getDocuments response requested without proof
226
228
  */
227
- export async function verifyDocumentsV1Signature(grpcPool, proof, metadata, rootHash) {
228
- const quorumPublicKey = await getQuorumPublicKey(grpcPool.network, proof.quorumType, bytesToHex(proof.quorumHash));
229
- const verify = await verifyTenderdashProof(proof, metadata, rootHash, quorumPublicKey);
230
- if (!verify) {
231
- throw new Error('Failed to verify query');
229
+ export function getDocumentsV1Data(result, kind) {
230
+ if (result.oneofKind !== 'data') {
231
+ throw new Error('Unexpected oneOf type returned from DAPI (must be data)');
232
232
  }
233
+ const { variant } = result.data;
234
+ if (variant.oneofKind !== kind) {
235
+ throw new Error(`Unexpected oneOf type returned from DAPI (must be ${String(kind)})`);
236
+ }
237
+ return variant[kind];
238
+ }
239
+ /**
240
+ * Deserializes the documents of a getDocuments response requested without proof
241
+ */
242
+ export function toDocuments(documents, dataContract, documentTypeName) {
243
+ return documents.map(bytes => DocumentWASM.fromBytes(bytes, dataContract, documentTypeName, LATEST_PLATFORM_VERSION));
244
+ }
245
+ /**
246
+ * Converts the document removal of a getDocuments response requested without proof to the one of the proof verification
247
+ */
248
+ export function toDocumentRemovalEntry(removal) {
249
+ const { documentId, documentOwnerId, moderatorId, removedAt, reason, documentHash, restoration, keptFields } = removal;
250
+ return {
251
+ documentId: new IdentifierWASM(documentId),
252
+ removal: {
253
+ documentOwnerId: new IdentifierWASM(documentOwnerId),
254
+ moderatorId: new IdentifierWASM(moderatorId),
255
+ reason: {
256
+ code: reason?.code ?? null,
257
+ text: reason?.text ?? '',
258
+ documents: reason?.documents.map(({ documentTypeName, documentId }) => ({ documentTypeName, documentId: new IdentifierWASM(documentId) })),
259
+ reasonDocumentId: reason?.reasonDocumentId != null ? new IdentifierWASM(reason.reasonDocumentId) : undefined
260
+ },
261
+ removedAt: BigInt(removedAt),
262
+ documentHash,
263
+ restoration: restoration != null
264
+ ? { moderatorId: new IdentifierWASM(restoration.moderatorId), restoredAt: BigInt(restoration.restoredAt) }
265
+ : null,
266
+ keptFields: keptFields.length > 0 ? keptFields : undefined
267
+ }
268
+ };
233
269
  }
@@ -3,7 +3,8 @@ import { Network } from '../types.js';
3
3
  export interface GRPCOptions {
4
4
  poolLimit?: number;
5
5
  dapiUrl?: string | string[];
6
- /** Custom connection pool, if set, `poolLimit` and `dapiUrl` are ignored **/
6
+ retries?: number;
7
+ /** Custom connection pool, if set, `poolLimit`, `dapiUrl` and `retries` are ignored **/
7
8
  pool?: GRPCPool;
8
9
  }
9
10
  /**
@@ -13,6 +14,14 @@ export interface GRPCOptions {
13
14
  export interface GRPCPool {
14
15
  network: Network;
15
16
  getClient: (abortController?: AbortController) => PlatformClient | Promise<PlatformClient>;
17
+ /** How many times a request is retried on another node, if not set, the SDK default is used **/
18
+ retries?: number;
19
+ /** Temporarily excludes the node that served the request of the client from node selection, e.g. after an invalid proof **/
20
+ banNode?: (client: PlatformClient) => void;
21
+ /** Lifts the ban of the node that served the request of the client, e.g. after its response was verified **/
22
+ unbanNode?: (client: PlatformClient) => void;
23
+ /** Requests and verifies proofs of the queries, `true` if not set **/
24
+ proofs?: boolean;
16
25
  }
17
26
  export interface MasternodeInfo {
18
27
  proTxHash: string;
@@ -32,15 +41,26 @@ export interface MasternodeInfo {
32
41
  collateraladdress: string;
33
42
  pubkeyoperator: string;
34
43
  }
35
- export declare const createClient: (url: string, abortController?: AbortController) => PlatformClient;
44
+ export declare const createClient: (url: string, abortController?: AbortController, fetch?: typeof globalThis.fetch) => PlatformClient;
36
45
  export default class GRPCConnectionPool implements GRPCPool {
37
46
  #private;
38
47
  dapiUrls: string[];
39
48
  network: Network;
49
+ readonly retries: number;
50
+ proofs?: boolean;
40
51
  constructor(network: Network, grpcOptions?: GRPCOptions);
41
- _initialize(network: Network, poolLimit: number, dapiUrl?: string | string[]): Promise<void>;
42
52
  /**
43
- * Waits for the pool initialization and returns a client connected to a random healthy node
53
+ * Waits for the pool initialization and returns a client connected to the next healthy node (round-robin)
44
54
  */
45
55
  getClient(abortController?: AbortController): Promise<PlatformClient>;
56
+ /**
57
+ * Bans the node that served the request of the client, e.g. when it returned an invalid proof.
58
+ * The first ban lasts 60 seconds, every next ban lasts e times longer, until the node is unbanned
59
+ */
60
+ banNode(client: PlatformClient): void;
61
+ /**
62
+ * Unbans the node that served the request of the client and resets its ban period,
63
+ * should be called once the response of the node was successfully verified
64
+ */
65
+ unbanNode(client: PlatformClient): void;
46
66
  }
@@ -2,10 +2,14 @@ import { GrpcWebFetchTransport } from '@protobuf-ts/grpcweb-transport';
2
2
  import { PlatformClient } from '../proto/generated/platform.client.js';
3
3
  import { GetStatusRequest } from '../proto/generated/platform.js';
4
4
  import getCurrentQuorumsInfo from './node/getCurrentQuorumsInfo.js';
5
- import getRandomArrayItem from './utils/getRandomArrayItem.js';
6
5
  import { fetchWithDetails } from './utils/fetchWithDetails.js';
7
6
  import { LATEST_PLATFORM_VERSION } from './constants.js';
7
+ import sleep from './utils/sleep.js';
8
8
  const GRPC_DEFAULT_POOL_LIMIT = 15;
9
+ const GRPC_DEFAULT_CONNECT_RETRIES = 5;
10
+ // first ban lasts 60 seconds, every next ban without a successful request in between lasts e times longer
11
+ const NODE_BASE_BAN_PERIOD_MS = 60 * 1000;
12
+ const RETRY_DELAY_MS = 10;
9
13
  const seedNodes = {
10
14
  testnet: [
11
15
  // seed-1.pshenmic.dev
@@ -45,11 +49,28 @@ const DAPI_PORTS = {
45
49
  const HEALTHCHECK_TIMEOUT_MS = 5000;
46
50
  // platform produces empty blocks every 3 minutes, so a healthy chain is never older than that
47
51
  const HEALTHCHECK_MAX_BLOCK_AGE_MS = 10 * 60 * 1000;
48
- export const createClient = (url, abortController) => {
52
+ const isAbortError = (error) => error instanceof Error && error.name === 'AbortError';
53
+ // errors raised before the request is sent to the node, so it is always safe to send it to another node
54
+ const CONNECT_ERROR_CODES = ['UND_ERR_CONNECT_TIMEOUT', 'ECONNREFUSED', 'EHOSTUNREACH', 'ENETUNREACH', 'EHOSTDOWN', 'ENETDOWN'];
55
+ /**
56
+ * Checks if the error (or one of its causes) means that the connection to the node could not be established
57
+ */
58
+ const isConnectError = (error) => {
59
+ if (!(error instanceof Error)) {
60
+ return false;
61
+ }
62
+ const { code } = error;
63
+ // ECONNRESET is a connect error only if the connection was reset during the TLS handshake,
64
+ // otherwise it may happen after the request was sent
65
+ return CONNECT_ERROR_CODES.includes(String(code)) ||
66
+ (code === 'ECONNRESET' && error.message.includes('before secure TLS connection was established')) ||
67
+ isConnectError(error.cause);
68
+ };
69
+ export const createClient = (url, abortController, fetch = fetchWithDetails) => {
49
70
  return new PlatformClient(new GrpcWebFetchTransport({
50
71
  baseUrl: url,
51
72
  abort: abortController?.signal,
52
- fetch: fetchWithDetails
73
+ fetch
53
74
  }));
54
75
  };
55
76
  /**
@@ -82,7 +103,7 @@ const isNodeHealthy = async (url) => {
82
103
  // node runs a protocol version that is not supported by the SDK
83
104
  // (e.g. newer software with incompatible proofs / responses)
84
105
  const protocol = version?.protocol?.drive;
85
- if (protocol == null || protocol.current !== Number(LATEST_PLATFORM_VERSION) || protocol?.latest !== Number(LATEST_PLATFORM_VERSION)) {
106
+ if (protocol == null || protocol.current !== Number(LATEST_PLATFORM_VERSION) || protocol.latest !== Number(LATEST_PLATFORM_VERSION)) {
86
107
  return false;
87
108
  }
88
109
  // chain is stalled, last block is too old relative to the node's own clock
@@ -111,30 +132,40 @@ export default class GRPCConnectionPool {
111
132
  network;
112
133
  #poolLimit;
113
134
  #dapiUrl;
135
+ retries;
136
+ proofs;
137
+ #nodeIndex = 0;
114
138
  #initialization;
139
+ // ban state of nodes that failed with a retryable error, banned nodes are skipped on node selection
140
+ #bans = new Map();
141
+ // node that served (or is serving) the request of the client
142
+ #clientNodes = new WeakMap();
115
143
  constructor(network, grpcOptions) {
144
+ const retries = grpcOptions?.retries ?? GRPC_DEFAULT_CONNECT_RETRIES;
145
+ if (!Number.isInteger(retries) || retries < 0) {
146
+ throw new Error(`GRPC retries must be a non-negative integer, got ${String(retries)}`);
147
+ }
116
148
  this.network = network;
117
149
  this.#poolLimit = grpcOptions?.poolLimit ?? GRPC_DEFAULT_POOL_LIMIT;
118
150
  this.#dapiUrl = grpcOptions?.dapiUrl;
151
+ this.retries = retries;
119
152
  // start initialization in the background, failures are reported on the first request
120
- this.#initialization = this._initialize(network, this.#poolLimit, this.#dapiUrl);
153
+ this.#initialization = this.#initializePool();
121
154
  this.#initialization.catch(() => { });
122
155
  }
123
- async _initialize(network, poolLimit, dapiUrl) {
124
- if (typeof dapiUrl === 'string') {
125
- this.dapiUrls = [dapiUrl];
126
- return;
127
- }
128
- if (Array.isArray(dapiUrl)) {
129
- this.dapiUrls = [...new Set(dapiUrl)];
156
+ async #initializePool() {
157
+ const { network } = this;
158
+ if (this.#dapiUrl != null) {
159
+ if (typeof this.#dapiUrl !== 'string' && !Array.isArray(this.#dapiUrl)) {
160
+ throw new Error('Unrecognized DAPI URL');
161
+ }
162
+ // trailing slash is removed, so the GRPC method path can be appended to the url
163
+ this.dapiUrls = [...new Set([this.#dapiUrl].flat().map(url => url.replace(/\/+$/, '')))];
130
164
  if (this.dapiUrls.length === 0) {
131
165
  throw new Error('DAPI URL list is empty');
132
166
  }
133
167
  return;
134
168
  }
135
- if (dapiUrl != null) {
136
- throw new Error('Unrecognized DAPI URL');
137
- }
138
169
  let quorumsInfo;
139
170
  const errors = [];
140
171
  for (const seed of seedNodes[network]) {
@@ -153,37 +184,27 @@ export default class GRPCConnectionPool {
153
184
  const networkDAPIUrls = shuffle([...new Set(quorumsInfo.validatorSets
154
185
  .flatMap(validatorSet => validatorSet.members)
155
186
  .filter(member => !member.isBanned)
156
- .map(member => `https://${member.nodeIp}:${DAPI_PORTS[network]}`))])
157
- .filter(url => !this.dapiUrls.includes(url));
187
+ .map(member => `https://${member.nodeIp}:${DAPI_PORTS[network]}`))]);
158
188
  // healthcheck nodes in parallel batches until the pool is full
159
- for (let i = 0; i < networkDAPIUrls.length && this.dapiUrls.length < poolLimit; i += poolLimit) {
160
- const batch = networkDAPIUrls.slice(i, i + poolLimit);
161
- await Promise.all(batch.map(async (url) => {
162
- if (await isNodeHealthy(url)) {
163
- this.#addNode(url, poolLimit);
164
- }
165
- }));
189
+ const dapiUrls = [];
190
+ for (let i = 0; i < networkDAPIUrls.length && dapiUrls.length < this.#poolLimit; i += this.#poolLimit) {
191
+ const batch = networkDAPIUrls.slice(i, i + this.#poolLimit);
192
+ const healthy = await Promise.all(batch.map(isNodeHealthy));
193
+ dapiUrls.push(...batch.filter((_, j) => healthy[j]));
166
194
  }
167
195
  // fail the initialization, so it is retried on the next request
168
- if (this.dapiUrls.length === 0) {
196
+ if (dapiUrls.length === 0) {
169
197
  throw new Error(`None of the ${network} evonodes are available (${networkDAPIUrls.length} checked, ` +
170
198
  `nodes must be synced and run protocol version ${Number(LATEST_PLATFORM_VERSION)})`);
171
199
  }
200
+ this.dapiUrls = dapiUrls.slice(0, this.#poolLimit);
172
201
  }
173
202
  /**
174
- * Adds a node to the pool, unless it is already there or the pool is full
175
- */
176
- #addNode(url, poolLimit) {
177
- if (!this.dapiUrls.includes(url) && this.dapiUrls.length < poolLimit) {
178
- this.dapiUrls.push(url);
179
- }
180
- }
181
- /**
182
- * Waits for the pool initialization and returns a client connected to a random healthy node
203
+ * Waits for the pool initialization and returns a client connected to the next healthy node (round-robin)
183
204
  */
184
205
  async getClient(abortController) {
185
206
  // retry initialization if the previous attempt failed
186
- this.#initialization ??= this._initialize(this.network, this.#poolLimit, this.#dapiUrl);
207
+ this.#initialization ??= this.#initializePool();
187
208
  const initialization = this.#initialization;
188
209
  try {
189
210
  await initialization;
@@ -195,7 +216,102 @@ export default class GRPCConnectionPool {
195
216
  }
196
217
  throw e;
197
218
  }
198
- const dapiUrl = getRandomArrayItem(this.dapiUrls);
199
- return createClient(dapiUrl, abortController);
219
+ if (this.dapiUrls.length === 0) {
220
+ throw new Error('DAPI URL list is empty');
221
+ }
222
+ const dapiUrl = this.#nextNode();
223
+ if (dapiUrl == null) {
224
+ throw new Error(`All ${this.dapiUrls.length} DAPI nodes are temporarily banned, no available nodes to send the request to`);
225
+ }
226
+ const client = createClient(dapiUrl, abortController, this.#createFetchWithRetry(dapiUrl, url => this.#clientNodes.set(client, url)));
227
+ this.#clientNodes.set(client, dapiUrl);
228
+ return client;
229
+ }
230
+ /**
231
+ * Bans the node that served the request of the client, e.g. when it returned an invalid proof.
232
+ * The first ban lasts 60 seconds, every next ban lasts e times longer, until the node is unbanned
233
+ */
234
+ banNode(client) {
235
+ const url = this.#clientNodes.get(client);
236
+ if (url != null) {
237
+ this.#ban(url);
238
+ }
239
+ }
240
+ /**
241
+ * Unbans the node that served the request of the client and resets its ban period,
242
+ * should be called once the response of the node was successfully verified
243
+ */
244
+ unbanNode(client) {
245
+ const url = this.#clientNodes.get(client);
246
+ if (url != null) {
247
+ this.#bans.delete(url);
248
+ }
249
+ }
250
+ #ban(url) {
251
+ // a single node is never banned, otherwise the pool would have no nodes to send requests to
252
+ if (this.dapiUrls.length <= 1) {
253
+ return;
254
+ }
255
+ const bannedTimes = this.#bans.get(url)?.bannedTimes ?? 0;
256
+ this.#bans.set(url, {
257
+ bannedTimes: bannedTimes + 1,
258
+ bannedUntil: Date.now() + NODE_BASE_BAN_PERIOD_MS * Math.exp(bannedTimes)
259
+ });
260
+ }
261
+ #isBanned(url) {
262
+ const ban = this.#bans.get(url);
263
+ return ban != null && ban.bannedUntil > Date.now();
264
+ }
265
+ /**
266
+ * Returns the next node from the pool in round-robin order, skipping the excluded and banned nodes.
267
+ * Every request and every retry moves to the next node, so the load is spread evenly
268
+ */
269
+ #nextNode(exclude = []) {
270
+ for (let i = 0; i < this.dapiUrls.length; i++) {
271
+ // index+1 and drop to 0 when #nodeIndex == this.dapiUrls.length
272
+ const url = this.dapiUrls[this.#nodeIndex++ % this.dapiUrls.length];
273
+ if (!exclude.includes(url) && !this.#isBanned(url)) {
274
+ return url;
275
+ }
276
+ }
277
+ return undefined;
278
+ }
279
+ /**
280
+ * Creates a fetch for the client of the given node, that retries the request
281
+ * on other nodes from the pool if it failed with a network error.
282
+ * The failed node is banned, `onNodeChange` is called with the node the request is retried on
283
+ */
284
+ #createFetchWithRetry(dapiUrl, onNodeChange) {
285
+ return async (input, init) => {
286
+ // transport always requests `${dapiUrl}/${service}/${method}`
287
+ const methodPath = String(input).slice(dapiUrl.length);
288
+ const triedUrls = [dapiUrl];
289
+ let nodeUrl = dapiUrl;
290
+ for (let retry = 0;; retry++) {
291
+ try {
292
+ return await fetchWithDetails(`${nodeUrl}${methodPath}`, init);
293
+ }
294
+ catch (e) {
295
+ // state transition could already be received by the node,
296
+ // so broadcast is retried only if the connection was not established
297
+ const isRetryable = methodPath.includes('broadcast') ? isConnectError(e) : !isAbortError(e);
298
+ if (!isRetryable || init?.signal?.aborted === true) {
299
+ throw e;
300
+ }
301
+ this.#ban(nodeUrl);
302
+ if (retry >= this.retries) {
303
+ throw e;
304
+ }
305
+ await sleep(RETRY_DELAY_MS);
306
+ const nextUrl = init?.signal?.aborted !== true ? this.#nextNode(triedUrls) : undefined;
307
+ if (nextUrl == null) {
308
+ throw e;
309
+ }
310
+ triedUrls.push(nextUrl);
311
+ nodeUrl = nextUrl;
312
+ onNodeChange(nextUrl);
313
+ }
314
+ }
315
+ };
200
316
  }
201
317
  }
@@ -1,3 +1,4 @@
1
1
  import { IdentifierLike } from 'pshenmic-dpp';
2
2
  import { GRPCPool } from '../grpcConnectionPool.js';
3
- export default function getIdentityBalance(grpcPool: GRPCPool, identifier: IdentifierLike): Promise<bigint>;
3
+ import { QuorumKeyProvider } from '../quorumKeyProvider.js';
4
+ export default function getIdentityBalance(grpcPool: GRPCPool, quorumKeyProvider: QuorumKeyProvider, identifier: IdentifierLike): Promise<bigint>;
@@ -1,10 +1,8 @@
1
1
  import { GetIdentityBalanceRequest } from '../../proto/generated/platform.js';
2
2
  import { IdentifierWASM, verifyIdentityBalanceProof } from 'pshenmic-dpp';
3
- import verifyTenderdashProof from '../utils/verifyTenderdashProof.js';
4
- import { getQuorumPublicKey } from '../utils/getQuorumPublicKey.js';
5
- import bytesToHex from '../utils/bytesToHex.js';
3
+ import QueryExecutor from '../QueryExecutor.js';
6
4
  import { LATEST_PLATFORM_VERSION } from '../constants.js';
7
- export default async function getIdentityBalance(grpcPool, identifier) {
5
+ export default async function getIdentityBalance(grpcPool, quorumKeyProvider, identifier) {
8
6
  const id = new IdentifierWASM(identifier);
9
7
  const getIdentityBalanceRequest = GetIdentityBalanceRequest.create({
10
8
  version: {
@@ -15,27 +13,15 @@ export default async function getIdentityBalance(grpcPool, identifier) {
15
13
  }
16
14
  }
17
15
  });
18
- const { response } = await (await grpcPool.getClient()).getIdentityBalance(getIdentityBalanceRequest);
19
- const { version } = response;
20
- if (version.oneofKind !== 'v0') {
21
- throw new Error('Unexpected oneOf type returned from DAPI (must be v0)');
22
- }
23
- const { v0 } = version;
24
- if (v0.result.oneofKind !== 'proof') {
25
- throw new Error('Unexpected oneOf type returned from DAPI (must be proof)');
26
- }
27
- const { result: { proof }, metadata } = v0;
28
- if (metadata == null) {
29
- throw new Error('Metadata not found');
30
- }
31
- const { rootHash, balance } = verifyIdentityBalanceProof(proof.grovedbProof, id.bytes(), true, LATEST_PLATFORM_VERSION);
32
- if (balance == null) {
33
- throw new Error(`Failed to fetch balance for identifier ${id.base58()}`);
34
- }
35
- const quorumPublicKey = await getQuorumPublicKey(grpcPool.network, proof.quorumType, bytesToHex(proof.quorumHash));
36
- const verify = await verifyTenderdashProof(proof, metadata, rootHash, quorumPublicKey);
37
- if (!verify) {
38
- throw new Error('Failed to verify query');
39
- }
40
- return BigInt(balance);
16
+ return await QueryExecutor.build(grpcPool, quorumKeyProvider)
17
+ .setGrpcRequest('getIdentityBalance', getIdentityBalanceRequest)
18
+ .setProofVerifier(verifyIdentityBalanceProof, id.bytes(), true, LATEST_PLATFORM_VERSION)
19
+ .mapResponse(data => {
20
+ const balance = data.proved ? data.verified.balance : BigInt(data.result.balance);
21
+ if (balance == null) {
22
+ throw new Error(`Failed to fetch balance for identifier ${id.base58()}`);
23
+ }
24
+ return balance;
25
+ })
26
+ .execute();
41
27
  }
@@ -1,3 +1,4 @@
1
1
  import { IdentifierLike, IdentityWASM } from 'pshenmic-dpp';
2
2
  import { GRPCPool } from '../grpcConnectionPool.js';
3
- export default function getIdentityByIdentifier(grpcPool: GRPCPool, identifier: IdentifierLike): Promise<IdentityWASM>;
3
+ import { QuorumKeyProvider } from '../quorumKeyProvider.js';
4
+ export default function getIdentityByIdentifier(grpcPool: GRPCPool, quorumKeyProvider: QuorumKeyProvider, identifier: IdentifierLike): Promise<IdentityWASM>;