Initial draft

Author: mohamed-mehany

packages/sources/nav-libre/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Chainlink External Adapter for nav-libre
+
+This README will be generated automatically when code is merged to `main`. If you would like to generate a preview of the README, please run `yarn generate:readme nav-libre`.

packages/sources/nav-libre/README.md

@@ -0,0 +1,44 @@
+{
+  "name": "@chainlink/nav-libre-adapter",
+  "version": "0.0.0",
+  "description": "Chainlink nav-libre adapter.",
+  "keywords": [
+    "Chainlink",
+    "LINK",
+    "blockchain",
+    "oracle",
+    "nav-libre"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "url": "https://github.com/smartcontractkit/external-adapters-js",
+    "type": "git"
+  },
+  "license": "MIT",
+  "scripts": {
+    "clean": "rm -rf dist && rm -f tsconfig.tsbuildinfo",
+    "prepack": "yarn build",
+    "build": "tsc -b",
+    "server": "node -e 'require(\"./index.js\").server()'",
+    "server:dist": "node -e 'require(\"./dist/index.js\").server()'",
+    "start": "yarn server:dist"
+  },
+  "devDependencies": {
+    "@types/crypto-js": "^4",
+    "@types/jest": "27.5.2",
+    "@types/node": "16.18.119",
+    "nock": "13.5.5",
+    "typescript": "5.6.3"
+  },
+  "dependencies": {
+    "@chainlink/external-adapter-framework": "2.6.0",
+    "crypto-js": "^4.2.0",
+    "dayjs": "^1.11.13",
+    "tslib": "2.4.1",
+    "uuid": "^11.1.0"
+  }
+}

packages/sources/nav-libre/package.json

@@ -0,0 +1,26 @@
+import { AdapterConfig } from '@chainlink/external-adapter-framework/config'
+
+export const config = new AdapterConfig({
+  API_KEY: {
+    description: 'An API key for Data Provider',
+    type: 'string',
+    required: true,
+    sensitive: true,
+  },
+  SECRET_KEY: {
+    description: 'A key for Data Provider used in hashing the API key',
+    type: 'string',
+    required: true,
+    sensitive: true,
+  },
+  API_ENDPOINT: {
+    description: 'An API endpoint for Data Provider',
+    type: 'string',
+    default: 'https://api.navfundservices.com/',
+  },
+  MAX_RETRIES: {
+    description: 'Maximum attempts of sending a request',
+    type: 'number',
+    default: 3,
+  },
+})

packages/sources/nav-libre/src/config/index.ts

@@ -0,0 +1 @@
+export { endpoint as nav } from './nav'

packages/sources/nav-libre/src/endpoint/index.ts

@@ -0,0 +1,56 @@
+import { AdapterEndpoint } from '@chainlink/external-adapter-framework/adapter'
+import { InputParameters } from '@chainlink/external-adapter-framework/validation'
+import dayjs from 'dayjs'
+import { config } from '../config'
+import { httpTransport } from '../transport/nav'
+
+// Input parameters define the structure of the request expected by the endpoint. The second parameter defines example input data that will be used in EA readme
+export const inputParameters = new InputParameters(
+  {
+    globalFundID: {
+      required: true,
+      type: 'number',
+      description: 'The global fund ID for the Libre fund',
+    },
+    fromDate: {
+      required: false,
+      type: 'string',
+      description: 'Start date in MM-DD-YYYY format (defaults to 7 days ago)',
+      default: dayjs().subtract(7, 'day').format('MM-DD-YYYY'),
+    },
+    toDate: {
+      required: false,
+      type: 'string',
+      description: 'End date in MM-DD-YYYY format (defaults to today)',
+      default: dayjs().format('MM-DD-YYYY'),
+    },
+  },
+  [
+    {
+      globalFundID: 139767,
+      fromDate: '12-30-2024',
+      toDate: '01-15-2025',
+    },
+  ],
+)
+export type NavResultResponse = {
+  Result: number
+  Data: {
+    navPerShare: number
+    navDate: string
+    globalFundID: number
+  }
+}
+
+export type BaseEndpointTypes = {
+  Parameters: typeof inputParameters.definition
+  Response: NavResultResponse
+  Settings: typeof config.settings
+}
+
+export const endpoint = new AdapterEndpoint({
+  name: 'nav',
+  aliases: [],
+  transport: httpTransport,
+  inputParameters,
+})

packages/sources/nav-libre/src/endpoint/nav.ts

@@ -0,0 +1,17 @@
+import { expose, ServerInstance } from '@chainlink/external-adapter-framework'
+import { Adapter } from '@chainlink/external-adapter-framework/adapter'
+import { config } from './config'
+import { nav } from './endpoint'
+
+export const adapter = new Adapter({
+  //Requests will direct to this endpoint if the `endpoint` input parameter is not specified.
+  defaultEndpoint: nav.name,
+  // Adapter name
+  name: 'NAV_LIBRE',
+  // Adapter configuration (environment variables)
+  config,
+  // List of supported endpoints
+  endpoints: [nav],
+})
+
+export const server = (): Promise<ServerInstance | undefined> => expose(adapter)

packages/sources/nav-libre/src/index.ts

@@ -0,0 +1,27 @@
+import CryptoJS from 'crypto-js'
+import { v4 as uuidv4 } from 'uuid'
+
+/**
+ * Generate the necessary headers for calling the NAV API with a 5-minute-valid signature.
+ */
+export const getNavRequestHeaders = (
+  method: string,
+  path: string,
+  body: string,
+  apiKey: string,
+  secret: string,
+) => {
+  const utcNow = new Date().toUTCString()
+  const nonce = uuidv4()
+  const contentHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Base64)
+  const stringToSign = [apiKey, path, method, utcNow, nonce, contentHash].join(';')
+
+  // 5. Compute the HMAC-SHA256 signature, Base64-encoded
+  const signature = CryptoJS.HmacSHA256(stringToSign, secret).toString(CryptoJS.enc.Base64)
+
+  return {
+    'x-date': utcNow,
+    'x-content-sha256': contentHash,
+    'x-hmac256-signature': `${apiKey};${nonce};${signature}`,
+  }
+}

packages/sources/nav-libre/src/transport/authentication.ts

@@ -0,0 +1,113 @@
+import { HttpTransport } from '@chainlink/external-adapter-framework/transports'
+import dayjs from 'dayjs'
+import { BaseEndpointTypes } from '../endpoint/nav'
+import { getNavRequestHeaders } from './authentication'
+
+export interface ResponseSchema {
+  Data: {
+    'Trading Level Net ROR': {
+      DTD: number
+      MTD: number
+      QTD: number
+      YTD: number
+      ITD: number
+    }
+    'Net ROR': {
+      DTD: number
+      MTD: number
+      QTD: number
+      YTD: number
+      ITD: number
+    }
+    'NAV Per Share': number
+    'Next NAV Price': number
+    'Accounting Date': string
+    'Ending Balance': number
+  }[]
+}
+
+// HttpTransport extends base types from endpoint and adds additional, Provider-specific types like 'RequestBody', which is the type of
+// request body (not the request to adapter, but the request that adapter sends to Data Provider), and 'ResponseBody' which is
+// the type of raw response from Data Provider
+export type HttpTransportTypes = BaseEndpointTypes & {
+  Provider: {
+    RequestBody: never
+    ResponseBody: ResponseSchema
+  }
+}
+// HttpTransport is used to fetch and process data from a Provider using HTTP(S) protocol. It usually needs two methods
+// `prepareRequests` and `parseResponse`
+export const httpTransport = new HttpTransport<HttpTransportTypes>({
+  prepareRequests: (params, config) => {
+    return params.map((param) => {
+      // Set defaults for fromDate and toDate if not provided
+      const now = dayjs()
+      const fromDate = param.fromDate || now.subtract(7, 'day').format('MM-DD-YYYY')
+      const toDate = param.toDate || now.format('MM-DD-YYYY')
+
+      // Validate date format MM-DD-YYYY
+      const dateRegex = /^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])-\d{4}$/
+      if (fromDate && !dateRegex.test(fromDate)) {
+        throw new Error('fromDate must be in MM-DD-YYYY format')
+      }
+      if (toDate && !dateRegex.test(toDate)) {
+        throw new Error('toDate must be in MM-DD-YYYY format')
+      }
+
+      const method = 'GET'
+      const path =
+        '/navapigateway/api/v1/FundAccountingData/GetOfficialNAVAndPerformanceReturnsForFund'
+      const query = `globalFundID=${param.globalFundID}&fromDate=${fromDate}&toDate=${toDate}`
+      const body = ''
+
+      const headers = getNavRequestHeaders(
+        method,
+        path + '?' + query,
+        body,
+        config.API_KEY,
+        config.SECRET_KEY,
+      )
+      return {
+        params: [param],
+        request: {
+          baseURL: config.API_ENDPOINT,
+          url: path,
+          headers,
+          params: {
+            globalFundID: param.globalFundID,
+            fromDate: param.fromDate,
+            toDate: param.toDate,
+          },
+        },
+      }
+    })
+  },
+  parseResponse: (params, response) => {
+    if (!response.data || !Array.isArray(response.data.Data) || response.data.Data.length === 0) {
+      return params.map((param) => ({
+        params: param,
+        response: {
+          errorMessage: `No NAV data returned for fund ${param.globalFundID}`,
+          statusCode: 502,
+        },
+      }))
+    }
+
+    // Find the latest NAV entry by Accounting Date
+    const latest = response.data.Data.reduce((a, b) => {
+      return new Date(a['Accounting Date']) > new Date(b['Accounting Date']) ? a : b
+    })
+
+    return params.map((param) => ({
+      params: param,
+      response: {
+        result: latest['NAV Per Share'],
+        data: {
+          navPerShare: latest['NAV Per Share'],
+          navDate: latest['Accounting Date'],
+          globalFundID: param.globalFundID,
+        },
+      },
+    }))
+  },
+})

packages/sources/nav-libre/src/transport/nav.ts

@@ -0,0 +1,6 @@
+{
+ "requests": [{
+  "from": "BTC",
+  "to": "USD"
+ }]
+}