@chainlink/external-adapter-framework 0.0.10 → 0.0.12

package/src/validation/error.ts

@@ -0,0 +1,116 @@
+import { HttpRequestType } from '../metrics/constants'
+
+type ErrorBasic = {
+  name: string
+  message: string
+}
+type ErrorFull = ErrorBasic & {
+  stack: string
+  cause: string
+}
+
+export type AdapterErrorResponse = {
+  jobRunID: string
+  status: string
+  statusCode: number
+  providerStatusCode?: number
+  error: ErrorBasic | ErrorFull
+}
+
+export class AdapterError extends Error {
+  jobRunID: string
+  status: string
+  statusCode: number
+  cause: any
+  url?: string
+  errorResponse: any
+  feedID?: string
+  providerStatusCode?: number
+  metricsLabel?: HttpRequestType
+
+  override name: string
+  override message: string
+
+  constructor({
+    jobRunID = '1',
+    status = 'errored',
+    statusCode = 500,
+    name = 'AdapterError',
+    message = 'An error occurred.',
+    cause,
+    url,
+    errorResponse,
+    feedID,
+    providerStatusCode,
+    metricsLabel = HttpRequestType.ADAPTER_ERROR,
+  }: Partial<AdapterError>) {
+    super(message)
+
+    this.jobRunID = jobRunID
+    this.status = status
+    this.statusCode = statusCode
+    this.name = name
+    this.message = message
+    this.cause = cause
+    if (url) {
+      this.url = url
+    }
+    if (feedID) {
+      this.feedID = feedID
+    }
+    this.errorResponse = errorResponse
+    this.providerStatusCode = providerStatusCode
+    this.metricsLabel = metricsLabel
+  }
+
+  toJSONResponse(): AdapterErrorResponse {
+    const showDebugInfo =
+      process.env['NODE_ENV'] === 'development' || process.env['DEBUG'] === 'true'
+    const errorBasic = {
+      name: this.name,
+      message: this.message,
+      url: this.url,
+      errorResponse: this.errorResponse,
+      feedID: this.feedID,
+    }
+    const errorFull = { ...errorBasic, stack: this.stack, cause: this.cause }
+    return {
+      jobRunID: this.jobRunID,
+      status: this.status,
+      statusCode: this.statusCode,
+      providerStatusCode: this.providerStatusCode,
+      error: showDebugInfo ? errorFull : errorBasic,
+    }
+  }
+}
+
+export class AdapterInputError extends AdapterError {
+  constructor(input: Partial<AdapterError>) {
+    super({ ...input, metricsLabel: HttpRequestType.INPUT_ERROR })
+  }
+}
+export class AdapterRateLimitError extends AdapterError {
+  constructor(input: Partial<AdapterError>) {
+    super({ ...input, metricsLabel: HttpRequestType.RATE_LIMIT_ERROR })
+  }
+}
+export class AdapterTimeoutError extends AdapterError {
+  constructor(input: Partial<AdapterError>) {
+    super({ ...input, metricsLabel: HttpRequestType.TIMEOUT_ERROR })
+  }
+}
+export class AdapterDataProviderError extends AdapterError {
+  constructor(input: Partial<AdapterError>) {
+    super({ ...input, metricsLabel: HttpRequestType.DP_ERROR })
+  }
+}
+export class AdapterConnectionError extends AdapterError {
+  constructor(input: Partial<AdapterError>) {
+    super({ ...input, metricsLabel: HttpRequestType.CONNECTION_ERROR })
+  }
+}
+export class AdapterCustomError extends AdapterError {
+  constructor(input: Partial<AdapterError>) {
+    super({ ...input, metricsLabel: HttpRequestType.CUSTOM_ERROR })
+  }
+}

package/src/validation/index.ts

@@ -0,0 +1,110 @@
+import { FastifyReply, FastifyRequest, HookHandlerDoneFunction } from 'fastify'
+import { InitializedAdapter } from '../adapter'
+import { calculateCacheKey } from '../cache'
+import { getMetricsMeta } from '../metrics/util'
+import { makeLogger } from '../util'
+import { AdapterMiddlewareBuilder, AdapterRequest } from '../util/request'
+import { AdapterError, AdapterInputError } from './error'
+import { Validator } from './validator'
+import { performSymbolOverrides } from './override-functions'
+export { InputParameters } from './input-params'
+
+const errorCatcherLogger = makeLogger('ErrorCatchingMiddleware')
+
+export const validatorMiddleware: AdapterMiddlewareBuilder =
+  (adapter: InitializedAdapter) =>
+  (req: AdapterRequest, reply: FastifyReply, done: HookHandlerDoneFunction) => {
+    if (req.headers['content-type'] !== 'application/json') {
+      throw new AdapterInputError({
+        message: 'Content type not "application/json", returning 400',
+        statusCode: 400,
+      })
+    }
+
+    if (!req.body) {
+      throw new AdapterInputError({
+        message: 'Body not present in adapter request, returning 400',
+        statusCode: 400,
+      })
+    }
+
+    // Make endpoints case insensitive
+    const endpointParam =
+      req.body.endpoint?.toLowerCase() ||
+      req.body.data?.endpoint?.toLowerCase() ||
+      adapter.defaultEndpoint
+    if (!endpointParam) {
+      throw new AdapterInputError({
+        message: `Request body does not specify an endpoint, and there is no default endpoint configured for this adapter.`,
+        statusCode: 400,
+      })
+    }
+
+    const endpoint = adapter.endpointsMap[endpointParam]
+    if (!endpoint) {
+      throw new AdapterInputError({
+        message: `Adapter does not have a "${endpointParam}" endpoint.`,
+        statusCode: 404,
+      })
+    }
+
+    // Validate data using validator from v2
+    // TODO: See if we want to change this whole thing
+    const validator = new Validator(req.body, endpoint.inputParameters)
+
+    req.requestContext = {
+      id: req.body.id || '1',
+      cacheKey: '',
+      data: validator.validated.data,
+      endpointName: endpoint.name,
+    }
+
+    if (adapter.config.METRICS_ENABLED && adapter.config.EXPERIMENTAL_METRICS_ENABLED) {
+      // Add metrics meta which includes feedId to the request
+      // Perform prior to overrides to maintain consistent Feed IDs across adapters
+      const metrics = getMetricsMeta(
+        {
+          adapterEndpoint: endpoint,
+          adapterConfig: adapter.config,
+        },
+        validator.validated.data,
+      )
+      req.requestContext = { ...req.requestContext, meta: { metrics } }
+    }
+
+    // TODO: Support `includes` and `tokenOverrides` overrides as needed
+    const requestParams = req.requestContext.data ?? {}
+    if (requestParams['tokenOverrides']) {
+      throw new Error('Token overrides not yet supported')
+    }
+    if (requestParams['includes']) {
+      throw new Error('Includes not yet supported')
+    }
+    // Swaps the 'base' parameter if any overrides are found in the request or the adapter configuration
+    // Supports 'base' input as string or string[]
+    performSymbolOverrides(adapter, req)
+
+    req.requestContext.cacheKey = calculateCacheKey(
+      {
+        adapterEndpoint: endpoint,
+        adapterConfig: adapter.config,
+      },
+      req.requestContext.data,
+    )
+
+    done()
+  }
+
+export const errorCatchingMiddleware = (err: Error, req: FastifyRequest, res: FastifyReply) => {
+  // Add adapter or generic error to request meta for metrics use
+  req.requestContext.meta = { ...req.requestContext.meta, error: err }
+  if (err instanceof AdapterError) {
+    // We want to log these as warn, because although they are to be expected, NOPs should
+    // Only use "correct" job specs and therefore not hit adapters with invalid requests.
+    errorCatcherLogger.warn(err)
+    res.status(err.statusCode).send(err.toJSONResponse())
+  } else {
+    errorCatcherLogger.error(err)
+    res.status(200).send('There was an unexpected error in the adapter.')
+  }
+}

package/src/validation/input-params.ts

@@ -0,0 +1,45 @@
+/* INPUT TYPE VALIDATIONS */
+export type Override = Map<string, Map<string, string>>
+
+export type InputParameter = {
+  aliases?: string[]
+  description?: string
+  type?: 'bigint' | 'boolean' | 'array' | 'number' | 'object' | 'string'
+  required?: boolean
+  options?: unknown[] // Enumerated options, ex. ['ADA', 'BTC', 'ETH']
+  default?: unknown
+  dependsOn?: string[] // Other inputs this one depends on
+  exclusive?: string[] // Other inputs that cannot be present with this one
+}
+
+export type InputParameters = {
+  [name: string]: InputParameter | boolean | string[]
+}
+export const baseInputParameters: InputParameters = {
+  endpoint: {
+    description: 'The External Adapter "endpoint" name to use.',
+    required: false,
+    type: 'string',
+  },
+  resultPath: {
+    description: 'The path to key into the API response the retrieve the result',
+    required: false,
+    // Type: 'string', TODO: Once multiple types are supported this could be string or array of strings
+  },
+  overrides: {
+    description: 'Override the mapping of token symbols to another token symbol',
+    required: false,
+    // Type: 'string', TODO: Once complex types are supported this could be { [adapter: string]: { [token: string]: string } }
+  },
+  tokenOverrides: {
+    description: 'Override the mapping of token symbols to smart contract address',
+    required: false,
+    // Type: 'string', TODO: Once complex types are supported this could be { [network: string]: { [token: string]: string } }
+  },
+  includes: {
+    description:
+      'Override the array of includes that holds additional input parameters when matching a pair of symbols',
+    required: false,
+    // Type: 'string', TODO: Once complex types are supported this could be { from: string, to: string, includes: [{ from: string, to: string, adapters: string[], inverse: boolean, tokens: boolean }] } }[]
+  },
+}

package/src/validation/override-functions.ts

@@ -0,0 +1,44 @@
+import { InitializedAdapter } from '../adapter'
+import { AdapterRequest } from '../util/request'
+
+type Overrides = Record<string, Record<string, string>>
+
+export const performSymbolOverrides = (adapter: InitializedAdapter, req: AdapterRequest) => {
+  let adapterOverrides = {} as Record<string, string>
+  if (
+    req.requestContext.data &&
+    req.requestContext.data['overrides'] &&
+    (req.requestContext.data['overrides'] as Overrides)[adapter.name]
+  ) {
+    adapterOverrides = (req.requestContext.data['overrides'] as Overrides)[adapter.name]
+  }
+  if (!Array.isArray(req.requestContext.data['base'])) {
+    // Perform overrides specified in the request payload
+    req.requestContext.data['base'] =
+      adapterOverrides[req.requestContext.data['base'] as string] ?? req.requestContext.data['base']
+    // Perform hardcoded overrides
+    if (adapter.overrides) {
+      req.requestContext.data['base'] =
+        adapter.overrides[req.requestContext.data['base'] as string] ??
+        req.requestContext.data['base']
+    }
+    return
+  }
+  let requestedSymbols = req.requestContext.data['base']
+  for (let i = 0; i < requestedSymbols.length; i++) {
+    const symbol = requestedSymbols[i]
+    // Perform overrides specified in the request payload
+    let overriddenSymbol =
+      adapterOverrides[symbol.toUpperCase()] ?? adapterOverrides[symbol.toLowerCase()]
+    // Perform hardcoded overrides
+    if (adapter.overrides) {
+      overriddenSymbol =
+        adapter.overrides[symbol.toUpperCase()] ??
+        adapter.overrides[symbol.toLowerCase()] ??
+        overriddenSymbol
+    }
+    requestedSymbols[i] = overriddenSymbol ?? requestedSymbols[i]
+  }
+  requestedSymbols = requestedSymbols.length > 1 ? requestedSymbols : requestedSymbols[1]
+  req.requestContext.data['base'] = requestedSymbols
+}

package/src/validation/preset-tokens.json

@@ -0,0 +1,23 @@
+{
+  "ethereum": {
+    "LINK": "0x514910771af9ca656af840dff83e8264ecf986ca",
+    "WETH": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
+    "ETH": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+    "stETH": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
+    "DIGG": "0x798d1be841a82a273720ce31c822c61a67a601c3",
+    "WBTC": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
+    "RAI": "0x03ab458634910aad20ef5f1c8ee96f1d6ac54919",
+    "RGT": "0xD291E7a03283640FDc51b121aC401383A46cC623",
+    "RARI": "0xFca59Cd816aB1eaD66534D82bc21E7515cE441CF",
+    "SFI": "0xb753428af26e81097e7fd17f40c88aaa3e04902c",
+    "LDO": "0x5a98fcbea516cf06857215779fd812ca3bef1b32",
+    "VSP": "0x1b40183EFB4Dd766f11bDa7A7c3AD8982e998421",
+    "USDC": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    "USDT": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+    "DAI": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+    "FRAX": "0x853d955aCEf822Db058eb8505911ED77F175b99e",
+    "BOND": "0x0391d2021f89dc339f60fff84546ea23e337750f",
+    "FEI": "0x956f47f50a910163d8bf957cf5846d573e7f87ca",
+    "TRIBE": "0xc7283b66Eb1EB5FB86327f08e1B5816b0720212B"
+  }
+}