@api3/commons 0.4.0 → 0.5.0

package/src/blockchain-utilities/derivation.ts

@@ -0,0 +1,116 @@
+import { ethers } from 'ethers';
+
+import { addressSchema } from './schema';
+
+export const PROTOCOL_IDS = {
+  RRP: '1',
+  PSP: '2',
+  RELAYED_RRP: '3',
+  RELAYED_PSP: '4',
+  AIRSEEKER: '5',
+};
+
+/**
+ * An interface that reflects the structure of a Template
+ */
+export interface Template {
+  airnode: string;
+  encodedParameters: string;
+  endpointId: string;
+}
+
+/**
+ * Derives a template ID from the input parameters
+ *
+ * @param airnode an Airnode address
+ * @param encodedParameters encoded parameters, see the airnode/abi package's encode function
+ * @param endpointId An endpointID (see deriveEndpointId)
+ */
+export const deriveTemplateId = ({ airnode, encodedParameters, endpointId }: Template) =>
+  ethers.utils.solidityKeccak256(['address', 'bytes32', 'bytes'], [airnode, endpointId, encodedParameters]);
+
+/**
+ * Derives an endpoint ID
+ *
+ * @param oisTitle the OIS title
+ * @param endpointName the endpoint name
+ */
+export const deriveEndpointId = (oisTitle: string, endpointName: string) =>
+  ethers.utils.keccak256(ethers.utils.defaultAbiCoder.encode(['string', 'string'], [oisTitle, endpointName]));
+
+/**
+ * Derives an airnode address's xpub, required for allowing signed data consumers to verify authenticity
+ *
+ * @param airnodeMnemonic the airnode's mnemonic
+ */
+export const deriveAirnodeXpub = (airnodeMnemonic: string) =>
+  ethers.utils.HDNode.fromMnemonic(airnodeMnemonic).derivePath("m/44'/60'/0'").neuter().extendedKey;
+
+/**
+ * Derives a wallet path from a sponsor address, used for calculating a sponsor wallet.
+ *
+ * @param sponsorAddress an EVM-compatible address
+ * @param protocolId an API application protocol ID
+ */
+export function deriveWalletPathFromSponsorAddress(sponsorAddress: string, protocolId: string) {
+  addressSchema.parse(sponsorAddress);
+
+  const sponsorAddressBN = ethers.BigNumber.from(sponsorAddress);
+  const paths = [];
+  for (let i = 0; i < 6; i++) {
+    const shiftedSponsorAddressBN = sponsorAddressBN.shr(31 * i);
+    paths.push(shiftedSponsorAddressBN.mask(31).toString());
+  }
+  return `${protocolId}/${paths.join('/')}`;
+}
+
+/**
+ * Encodes/formats a string as a hex-encoded bytes32 string.
+ *
+ * @param input the input string
+ */
+export const toBytes32String = (input: string) => ethers.utils.formatBytes32String(input);
+
+/**
+ * Decodes a hex-encoded bytes32 string to a normal string.
+ *
+ * @param input the input hex string
+ */
+export const fromBytes32String = (input: string) => ethers.utils.parseBytes32String(input);
+
+/**
+ * Derives a sponsor wallet, given a mnemonic and dapiName.
+ *
+ * @param sponsorWalletMnemonic the sponsor wallet mnemonic
+ * @param dapiName the dapi name
+ */
+export const deriveSponsorWallet = (sponsorWalletMnemonic: string, dapiName: string) => {
+  // Take first 20 bytes of dapiName as sponsor address together with the "0x" prefix.
+  const sponsorAddress = ethers.utils.getAddress(dapiName.slice(0, 42));
+  const sponsorWallet = ethers.Wallet.fromMnemonic(
+    sponsorWalletMnemonic,
+    `m/44'/60'/0'/${
+      (deriveWalletPathFromSponsorAddress(sponsorAddress, PROTOCOL_IDS.AIRSEEKER), PROTOCOL_IDS.AIRSEEKER)
+    }`
+  );
+
+  return sponsorWallet;
+};
+
+/**
+ * Derives the ID of a single beacon
+ *
+ * @param airnodeAddress the airnode address of the provider that supplies the data used to update this beacon
+ * @param templateId the templateId of the template used to generate the data used to update this beacon
+ */
+export const deriveBeaconId = (airnodeAddress: string, templateId: string) =>
+  ethers.utils.solidityKeccak256(['address', 'bytes32'], [airnodeAddress, templateId]);
+
+/**
+ * Derives the ID of a set of beacons.
+ * By convention beacon IDs are sorted alphabetically - the ordering impacts the resulting hash.
+ *
+ * @param beaconIds an ordered array of beacon ids
+ */
+export const deriveBeaconSetId = (beaconIds: string[]) =>
+  ethers.utils.keccak256(ethers.utils.defaultAbiCoder.encode(['bytes32[]'], [beaconIds]));

package/src/blockchain-utilities/schema.test.ts

@@ -0,0 +1,23 @@
+import { addressSchema, idSchema } from './schema';
+
+describe('schema', () => {
+  it('validates a valid address', () => {
+    expect(() => addressSchema.parse('0x8A45eac0267dD0803Fd957723EdE10693A076698')).not.toThrow();
+  });
+
+  it('throws for an invalid address', () => {
+    expect(() => addressSchema.parse('0xA8A45eac0267dD0803Fd957723EdE10693A076698')).toThrow(
+      expect.objectContaining({ name: 'ZodError' })
+    );
+  });
+
+  it('validates a valid ID', () => {
+    expect(() => idSchema.parse('0x3528e42b017a5fbf9d2993a2df04efc3ed474357575065a111b054ddf9de2acc')).not.toThrow();
+  });
+
+  it('throws for an invalid ID', () => {
+    expect(() => idSchema.parse('0xA3528e42b017a5fbf9d2993a2df04efc3ed474357575065a111b054ddf9de2acc')).toThrow(
+      expect.objectContaining({ name: 'ZodError' })
+    );
+  });
+});

package/src/blockchain-utilities/schema.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+/**
+ * A Zod validation schema that represents an EVM-compatible address.
+ */
+export const addressSchema = z.string().regex(/^0x[\dA-Fa-f]{40}$/, 'Must be a valid EVM address');
+
+/**
+ * A Zod validation schema that represents an EVM-compatible hash, which includes beacon IDs and template IDs.
+ */
+export const idSchema = z.string().regex(/^0x[\dA-Fa-f]{64}$/, 'Must be a valid EVM hash');
+
+export type Address = z.infer<typeof addressSchema>;
+export type Id = z.infer<typeof idSchema>;

package/src/logger/index.test.ts

@@ -108,4 +108,20 @@ describe('log context', () => {
       })
     ).rejects.toThrow('some-error');
   });
+
+  it('can log using all variants of logger.error', () => {
+    const { baseLogger, logger } = createTestLogger();
+
+    logger.error('only message');
+    logger.error('message and context', { requestId: 'parent' });
+    logger.error('message and error', new Error('some-error'));
+    logger.error('message, error and context', new Error('some-error'), { requestId: 'parent' });
+
+    expect(baseLogger.error).toHaveBeenNthCalledWith(1, 'only message', undefined);
+    expect(baseLogger.error).toHaveBeenNthCalledWith(2, 'message and context', { requestId: 'parent' });
+    expect(baseLogger.error).toHaveBeenNthCalledWith(3, 'message and error', new Error('some-error'), undefined);
+    expect(baseLogger.error).toHaveBeenNthCalledWith(4, 'message, error and context', new Error('some-error'), {
+      requestId: 'parent',
+    });
+  });
 });

package/src/logger/index.ts

@@ -79,9 +79,12 @@ export interface Logger {
   debug: (message: string, context?: LogContext) => void;
   info: (message: string, context?: LogContext) => void;
   warn: (message: string, context?: LogContext) => void;
-  error:
-    | ((message: string, context?: LogContext) => void)
-    | ((message: string, error: Error, context?: LogContext) => void);
+  // We need to handle both overloads of the `error` function. It may a bit surprising that the variants are joined with
+  // "&" instead of "|", but it forces TypeScript to be more deliberate when resolving overloads. For functions, this
+  // means the implementation must handle all overloads, and TypeScript will look for the correct overload based on the
+  // arguments provided.
+  error: ((message: string, context?: LogContext) => void) &
+    ((message: string, error: Error, context?: LogContext) => void);
   child: (options: { name: string }) => Logger;
 }
 
@@ -105,7 +108,7 @@ export const wrapper = (logger: winston.Logger): Logger => {
       logger.warn(message, fullContext);
     },
     // We need to handle both overloads of the `error` function
-    error: (message, errorOrLocalContext, localContext) => {
+    error: (message, errorOrLocalContext: Error | LogContext, localContext?: LogContext) => {
       const globalContext = getAsyncLocalStorage().getStore();
       // eslint-disable-next-line lodash/prefer-lodash-typecheck
       if (errorOrLocalContext instanceof Error) {
@@ -113,7 +116,7 @@ export const wrapper = (logger: winston.Logger): Logger => {
         logger.error(message, errorOrLocalContext, fullContext);
       } else {
         const fullContext =
-          globalContext || errorOrLocalContext ? { ...globalContext, ...(errorOrLocalContext as any) } : undefined;
+          globalContext || errorOrLocalContext ? { ...globalContext, ...errorOrLocalContext } : undefined;
         logger.error(message, fullContext);
       }
     },

package/src/processing/README.md

@@ -6,40 +6,115 @@ The pre/post processing is only supported for Node.js environments and uses inte
 
 ## Documentation
 
-The processing module exports two main functions:
+The processing module exports a multiple functions related to processing (both version 1 and 2). The most important
+functions are:
 
 <!-- NOTE: These are copied over from "processing.d.ts" from "dist" file. -->
 
 ```ts
 /**
- * Pre-processes API call parameters based on the provided endpoint's processing specifications.
+ * Pre-processes endpoint parameters based on the provided endpoint's processing specifications.
+ *
+ * @param preProcessingSpecifications The v1 pre-processing specifications.
+ * @param endpointParameters The parameters to be pre-processed.
+ * @param processingOptions Options to control the async processing behavior like retries and timeouts.
+ *
+ * @returns A promise that resolves to the pre-processed parameters.
+ */
+export declare const preProcessEndpointParametersV1: (
+  preProcessingSpecifications: ProcessingSpecifications | undefined,
+  endpointParameters: EndpointParameters,
+  processingOptions?: GoAsyncOptions
+) => Promise<EndpointParameters>;
+
+/**
+ * Post-processes the response based on the provided endpoint's processing specifications. The response is usually the
+ * API call response, but this logic depends on how the processing is used by the target service. For example, Airnode
+ * allows skipping API calls in which case the response is the result of pre-processing.
+ *
+ * @param response The response to be post-processed.
+ * @param postProcessingSpecifications The v1 post-processing specifications.
+ * @param endpointParameters The endpoint parameters.
+ * @param processingOptions Options to control the async processing behavior like retries and timeouts.
+ *
+ * @returns A promise that resolves to the post-processed response.
+ */
+export declare const postProcessResponseV1: (
+  response: unknown,
+  postProcessingSpecifications: ProcessingSpecifications | undefined,
+  endpointParameters: EndpointParameters,
+  processingOptions?: GoAsyncOptions
+) => Promise<unknown>;
+
+/**
+ * Pre-processes endpoint parameters based on the provided endpoint's processing specifications.
+ *
+ * @param preProcessingSpecificationV2 The v2 pre-processing specification.
+ * @param endpointParameters The parameters to be pre-processed.
+ * @param processingOptions Options to control the async processing behavior like retries and timeouts.
+ *
+ * @returns A promise that resolves to the pre-processed parameters.
+ */
+export declare const preProcessEndpointParametersV2: (
+  preProcessingSpecificationV2: ProcessingSpecificationV2 | undefined,
+  endpointParameters: EndpointParameters,
+  processingOptions?: GoAsyncOptions
+) => Promise<PreProcessingV2Response>;
+
+/**
+ * Post-processes the response based on the provided endpoint's processing specifications. The response is usually the
+ * API call response, but this logic depends on how the processing is used by the target service. For example, Airnode
+ * allows skipping API calls in which case the response is the result of pre-processing.
+ *
+ * @param response The response to be post-processed.
+ * @param postProcessingSpecificationV2 The v2 post-processing specification.
+ * @param endpointParameters The endpoint parameters.
+ * @param processingOptions Options to control the async processing behavior like retries and timeouts.
+ *
+ * @returns A promise that resolves to the post-processed response.
+ */
+export declare const postProcessResponseV2: (
+  response: unknown,
+  postProcessingSpecificationV2: ProcessingSpecificationV2 | undefined,
+  endpointParameters: EndpointParameters,
+  processingOptions?: GoAsyncOptions
+) => Promise<PostProcessingV2Response>;
+
+/**
+ * Pre-processes endpoint parameters based on the provided endpoint's processing specifications. Internally it
+ * determines what processing implementation should be used.
  *
  * @param endpoint The endpoint containing processing specifications.
- * @param apiCallParameters The parameters to be pre-processed.
+ * @param endpointParameters The parameters to be pre-processed.
  * @param processingOptions Options to control the async processing behavior like retries and timeouts.
  *
  * @returns A promise that resolves to the pre-processed parameters.
  */
-export declare const preProcessApiCallParameters: (
+export declare const preProcessEndpointParameters: (
   endpoint: Endpoint,
-  apiCallParameters: ApiCallParameters,
+  endpointParameters: EndpointParameters,
   processingOptions?: GoAsyncOptions
-) => Promise<ApiCallParameters>;
+) => Promise<PreProcessingV2Response>;
 
 /**
- * Post-processes the API call response based on the provided endpoint's processing specifications.
+ * Post-processes the response based on the provided endpoint's processing specifications. The response is usually the
+ * API call response, but this logic depends on how the processing is used by the target service. For example, Airnode
+ * allows skipping API calls in which case the response is the result of pre-processing.
  *
- * @param apiCallResponse The raw response obtained from the API call.
+ * This function determines what processing version should be used and provides a common interface. This is useful for
+ * services that want to use processing and don't care which processing version is used.
+ *
+ * @param response The response to be post-processed.
  * @param endpoint The endpoint containing processing specifications.
- * @param apiCallParameters The parameters used in the API call.
+ * @param endpointParameters The endpoint parameters.
  * @param processingOptions Options to control the async processing behavior like retries and timeouts.
  *
- * @returns A promise that resolves to the post-processed API call response.
+ * @returns A promise that resolves to the post-processed response.
  */
-export declare const postProcessApiCallResponse: (
-  apiCallResponse: unknown,
+export declare const postProcessResponse: (
+  response: unknown,
   endpoint: Endpoint,
-  apiCallParameters: ApiCallParameters,
+  endpointParameters: EndpointParameters,
   processingOptions?: GoAsyncOptions
-) => Promise<unknown>;
+) => Promise<PostProcessingV2Response>;
 ```