@chainlink/external-adapter-framework 0.0.6 → 0.0.8

package/config/index.js

@@ -0,0 +1,365 @@
+"use strict";
+// Import { getRandomRequiredEnv, getRandomEnv, getEnv } from '../util'
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAdapterConfig = exports.BaseSettings = void 0;
+exports.BaseSettings = {
+    // V2 compat
+    // TODO: Remove non used in v3 ones
+    // API_ENDPOINT: {
+    //   type: 'string',
+    // },
+    API_KEY: {
+        description: 'Default setting for an EA key',
+        type: 'string',
+    },
+    // API_TIMEOUT: {
+    //   type: 'number',
+    //   default: 30000,
+    // },
+    // API_VERBOSE: {
+    //   type: 'boolean',
+    // },
+    BASE_URL: {
+        description: 'Starting path for the EA handler endpoint',
+        type: 'string',
+        default: '/',
+    },
+    // CACHE_ENABLED: {
+    //   type: 'boolean',
+    //   default: true,
+    // },
+    // CACHE_KEY_GROUP: {
+    //   type: 'string',
+    // },
+    CACHE_MAX_AGE: {
+        description: 'Maximum amount of time (in ms) that a response will stay cached',
+        type: 'number',
+        default: 90000,
+    },
+    // CACHE_MAX_ITEMS: {
+    //   type: 'number',
+    //   default: 1000,
+    // },
+    // CACHE_MIN_AGE: {
+    //   type: 'number',
+    //   default: 30000,
+    // },
+    // CACHE_REDIS_CONNECTION_TIMEOUT: {
+    //   type: 'number',
+    //   default: 15000,
+    // },
+    CACHE_REDIS_HOST: {
+        description: 'Hostname for the Redis instance to be used',
+        type: 'string',
+        default: '127.0.0.1',
+    },
+    // CACHE_REDIS_MAX_QUEUED_ITEMS: {
+    //   type: 'number',
+    //   default: 100,
+    // },
+    // CACHE_REDIS_MAX_RECONNECT_COOLDOWN: {
+    //   type: 'number',
+    //   default: 3000,
+    // },
+    // CACHE_REDIS_PASSWORD: {
+    //   type: 'string',
+    // },
+    // CACHE_REDIS_PATH: {
+    //   type: 'string',
+    // },
+    CACHE_REDIS_PORT: {
+        description: 'Port for the Redis instance to be used',
+        type: 'number',
+        default: 6379,
+    },
+    // CACHE_REDIS_TIMEOUT: {
+    //   type: 'number',
+    //   default: 500,
+    // },
+    // CACHE_REDIS_URL: {
+    //   type: 'string',
+    // },
+    CACHE_TYPE: {
+        description: 'The type of cache to use throughout the EA',
+        type: 'enum',
+        default: 'local',
+        options: ['local', 'redis'],
+    },
+    // CACHE_UPDATE_AGE_ON_GET: {
+    //   type: 'boolean',
+    //   default: false,
+    // },
+    CORRELATION_ID_ENABLED: {
+        description: 'Flag to enable correlation IDs for sent requests in logging',
+        type: 'boolean',
+        default: true,
+    },
+    // DEBUG: {
+    //   type: 'boolean',
+    // },
+    // DEFAULT_WS_HEARTBEAT_INTERVAL: {
+    //   type: 'number',
+    //   default: 30000,
+    // },
+    EA_PORT: {
+        description: 'Port through which the EA will listen for REST requests (if mode is set to "reader" or "reader-writer")',
+        type: 'number',
+        default: 8080,
+    },
+    // ENV_ADAPTER_URL: {
+    //   type: 'string',
+    // },
+    // ERROR_CAPACITY: {
+    //   type: 'number',
+    // },
+    EXPERIMENTAL_METRICS_ENABLED: {
+        description: 'Flag to specify whether or not to collect metrics. Used as fallback for METRICS_ENABLED',
+        type: 'boolean',
+        default: true,
+    },
+    // LEGACY_ENV_ADAPTER_URL: {
+    //   type: 'string',
+    // },
+    LOG_LEVEL: {
+        description: 'Minimum level required for logs to be output',
+        type: 'string',
+        default: 'info',
+    },
+    METRICS_ENABLED: {
+        description: 'Flag to specify whether or not to startup the metrics server',
+        type: 'boolean',
+        default: true,
+    },
+    METRICS_NAME: {
+        description: 'Metrics name',
+        type: 'string',
+    },
+    METRICS_PORT: {
+        description: 'Port metrics will be exposed to',
+        type: 'number',
+        default: 9080,
+    },
+    METRICS_USE_BASE_URL: {
+        description: 'Flag to specify whether or not to prepend the BASE_URL to the metrics endpoint',
+        type: 'boolean',
+    },
+    RATE_LIMIT_API_TIER: {
+        description: 'Rate limiting tier to use from the available options for the adapter. If not present, the adapter will run using the first tier on the list.',
+        type: 'string',
+    },
+    // RATE_LIMIT_CAPACITY_MINUTE: {
+    //   type: 'number',
+    // },
+    // RATE_LIMIT_CAPACITY_SECOND: {
+    //   type: 'number',
+    // },
+    // RATE_LIMIT_CAPACITY: {
+    //   type: 'number',
+    // },
+    // RATE_LIMIT_ENABLED: {
+    //   type: 'boolean',
+    //   default: true,
+    // },
+    // RECORD: {
+    //   type: 'boolean',
+    // },
+    // REQUEST_COALESCING_ENABLED: {
+    //   type: 'boolean',
+    // },
+    // REQUEST_COALESCING_ENTROPY_MAX: {
+    //   type: 'number',
+    //   default: 0,
+    // },
+    // REQUEST_COALESCING_INTERVAL_COEFFICIENT: {
+    //   type: 'number',
+    //   default: 2,
+    // },
+    // REQUEST_COALESCING_INTERVAL_MAX: {
+    //   type: 'number',
+    //   default: 1000,
+    // },
+    // REQUEST_COALESCING_INTERVAL: {
+    //   type: 'number',
+    //   default: 100,
+    // },
+    // REQUEST_COALESCING_MAX_RETRIES: {
+    //   type: 'number',
+    //   default: 5,
+    // },
+    // RETRY: {
+    //   type: 'boolean',
+    //   default: 1,
+    // },
+    // SERVER_RATE_LIMIT_MAX: {
+    //   type: 'number',
+    //   default: 250,
+    // },
+    // SERVER_SLOW_DOWN_AFTER_FACTOR: {
+    //   type: 'number',
+    //   default: 0.8,
+    // },
+    // SERVER_SLOW_DOWN_DELAY_MS: {
+    //   type: 'number',
+    //   default: 500,
+    // },
+    // TIMEOUT: {
+    //   type: 'number',
+    // },
+    // WARMUP_ENABLED: {
+    //   type: 'boolean',
+    //   default: true,
+    // },
+    // WARMUP_INTERVAL: {
+    //   type: 'number',
+    // },
+    WARMUP_SUBSCRIPTION_TTL: {
+        type: 'number',
+        description: '',
+        default: 10000,
+    },
+    // WARMUP_UNHEALTHY_THRESHOLD: {
+    //   type: 'number',
+    //   default: 3,
+    // },
+    // WS_API_ENDPOINT: {
+    //   type: 'string',
+    // },
+    // WS_API_KEY: {
+    //   type: 'string',
+    // },
+    // WS_CONNECTION_KEY: {
+    //   type: 'string',
+    //   default: 1,
+    // },
+    // WS_CONNECTION_LIMIT: {
+    //   type: 'number',
+    //   default: 1,
+    // },
+    // WS_CONNECTION_RETRY_DELAY: {
+    //   type: 'number',
+    //   default: 1000,
+    // },
+    // WS_CONNECTION_RETRY_LIMIT: {
+    //   type: 'number',
+    //   default: 3,
+    // },
+    // WS_CONNECTION_TTL: {
+    //   type: 'number',
+    //   default: 70000,
+    // },
+    // WS_ENABLED: {
+    //   type: 'boolean',
+    //   default: false,
+    // },
+    // WS_SUBSCRIPTION_LIMIT: {
+    //   type: 'number',
+    //   default: 10,
+    // },
+    // WS_SUBSCRIPTION_PRIORITY_LIST: {
+    //   type: 'string',
+    // },
+    // WS_SUBSCRIPTION_TTL: {
+    //   type: 'number',
+    //   default: 120000,
+    // },
+    // WS_SUBSCRIPTION_UNRESPONSIVE_TTL: {
+    //   type: 'number',
+    //   default: false,
+    // },
+    // WS_TIME_UNTIL_HANDLE_NEXT_MESSAGE_OVERRIDE: {
+    //   type: 'number',
+    // },
+    // V3
+    CACHE_POLLING_MAX_RETRIES: {
+        description: 'Max amount of times to attempt to find EA response in the cache after the Transport has been set up',
+        type: 'number',
+        default: 10,
+    },
+    CACHE_POLLING_SLEEP_MS: {
+        description: 'The number of ms to sleep between each retry to fetch the EA response in the cache',
+        type: 'number',
+        default: 200,
+    },
+    DEFAULT_CACHE_KEY: {
+        description: 'Default key to be used when one cannot be determined from request parameters',
+        type: 'string',
+        default: 'DEFAULT_CACHE_KEY',
+    },
+    EA_HOST: {
+        description: 'Host this EA will listen for REST requests on (if mode is set to "reader" or "reader-writer")',
+        type: 'string',
+        default: '::',
+    },
+    EA_MODE: {
+        description: 'Port this EA will listen for REST requests on (if mode is set to "reader" or "reader-writer")',
+        type: 'enum',
+        default: 'reader-writer',
+        options: ['reader', 'writer', 'reader-writer'],
+    },
+    REST_TRANSPORT_MAX_RATE_LIMIT_RETRIES: {
+        description: 'Maximum amount of times the Rest Transport will attempt to set up a request when blocked by the rate limiter',
+        type: 'number',
+        default: 3,
+    },
+    REST_TRANSPORT_MS_BETWEEN_RATE_LIMIT_RETRIES: {
+        description: 'Time that the Rest Transport will wait between retries when blocked by the rate limiter',
+        type: 'number',
+        default: 400,
+    },
+    // CACHE_KEY_IGNORED_PROPS : {
+    //   description: 'Properties to ignore when generating a feed ID for requests',
+    //   type: 'string'
+    // }
+};
+const buildAdapterConfig = ({ overrides = {}, customSettings = {}, }) => {
+    const validationErrors = [];
+    const vars = {};
+    // Iterate base adapter env vars
+    for (const [key, config] of Object.entries(exports.BaseSettings)) {
+        const value = getEnv(key, config) ?? overrides?.[key] ?? config.default;
+        vars[key] = value;
+    }
+    // Iterate custom vars
+    for (const [key, config] of Object.entries(customSettings)) {
+        if (exports.BaseSettings[key]) {
+            throw new Error(`Custom env var "${key}" declared, but a base framework env var with that name already exists.`);
+        }
+        const value = getEnv(key, config) ?? config.default;
+        // Check if a required setting has been provided
+        if (config.required && value === null) {
+            validationErrors.push(`${key}: Value is required, but none was provided`);
+        }
+        else if (config.validate) {
+            // Cast validate to unknown because TS can't select one of multiple variants of the validate function signature
+            const validationRes = config.validate(value);
+            if (validationRes) {
+                validationErrors.push(`${key}: ${validationRes}`);
+            }
+        }
+        vars[key] = value;
+    }
+    if (validationErrors.length > 0) {
+        throw new Error(`Validation failed for the following variables:\n ${validationErrors.join('\n')}`);
+    }
+    return vars;
+};
+exports.buildAdapterConfig = buildAdapterConfig;
+const getEnv = (name, config) => {
+    const value = process.env[name];
+    if (!value) {
+        return null;
+    }
+    switch (config.type) {
+        case 'string':
+            return value;
+        case 'number':
+            return parseInt(value);
+        case 'boolean':
+            return value === 'true';
+        case 'enum':
+            if (!config.options?.includes(value)) {
+                throw new Error(`Env var "${name}" has value "${value}" which is not included in the valid options (${config.options})`);
+            }
+            return value;
+    }
+};

package/config/provider-limits.d.ts

@@ -0,0 +1,31 @@
+export declare const DEFAULT_MINUTE_RATE_LIMIT = 60;
+export declare const BURST_UNDEFINED_QUOTA_MULTIPLE = 2;
+export declare const DEFAULT_WS_CONNECTIONS = 2;
+export declare const DEFAULT_WS_SUBSCRIPTIONS = 10;
+declare type RateLimitTimeFrame = 'rateLimit1s' | 'rateLimit1m' | 'rateLimit1h';
+declare type HTTPTier = {
+    rateLimit1s?: number;
+    rateLimit1m?: number;
+    rateLimit1h?: number;
+    note?: string;
+};
+declare type WSTier = {
+    connections: number;
+    subscriptions: number;
+};
+export interface Limits {
+    http: {
+        [tierName: string]: HTTPTier;
+    };
+    ws: {
+        [tierName: string]: WSTier;
+    };
+}
+interface ProviderRateLimit {
+    second: number;
+    minute: number;
+}
+export declare const getHTTPLimit: (provider: string, limits: Limits, tier: string, timeframe: RateLimitTimeFrame) => number;
+export declare const getRateLimit: (provider: string, limits: Limits, tier: string) => ProviderRateLimit;
+export declare const getWSLimits: (provider: string, limits: Limits, tier: string) => WSTier;
+export {};

package/config/provider-limits.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWSLimits = exports.getRateLimit = exports.getHTTPLimit = exports.DEFAULT_WS_SUBSCRIPTIONS = exports.DEFAULT_WS_CONNECTIONS = exports.BURST_UNDEFINED_QUOTA_MULTIPLE = exports.DEFAULT_MINUTE_RATE_LIMIT = void 0;
+const util_1 = require("../util");
+exports.DEFAULT_MINUTE_RATE_LIMIT = 60;
+exports.BURST_UNDEFINED_QUOTA_MULTIPLE = 2;
+exports.DEFAULT_WS_CONNECTIONS = 2;
+exports.DEFAULT_WS_SUBSCRIPTIONS = 10;
+const logger = (0, util_1.makeLogger)('ProviderLimits');
+const getHTTPLimit = (provider, limits, tier, timeframe) => {
+    const providerLimit = getProviderLimits(provider, limits, tier, 'http');
+    return providerLimit?.[timeframe] || 0;
+};
+exports.getHTTPLimit = getHTTPLimit;
+const getRateLimit = (provider, limits, tier) => {
+    const providerLimit = getProviderLimits(provider, limits, tier, 'http');
+    return calculateRateLimit(providerLimit);
+};
+exports.getRateLimit = getRateLimit;
+const getWSLimits = (provider, limits, tier) => {
+    const providerLimit = getProviderLimits(provider, limits, tier, 'ws');
+    return calculateWSLimits(providerLimit);
+};
+exports.getWSLimits = getWSLimits;
+const getProviderLimits = (provider, limits, tier, protocol) => {
+    const providerConfig = parseLimits(limits);
+    if (!providerConfig) {
+        throw new Error(`Rate Limit: Provider: "${provider}" doesn't match any provider spec in limits.json`);
+    }
+    const protocolConfig = providerConfig[protocol];
+    if (!protocolConfig) {
+        throw new Error(`Rate Limit: "${provider}" doesn't have any configuration for ${protocol} in limits.json`);
+    }
+    let limitsConfig = protocolConfig[tier.toLowerCase()];
+    if (!limitsConfig) {
+        logger.debug(`Rate Limit: "${provider} does not have tier ${tier} defined. Falling back to lowest tier"`);
+        limitsConfig = Object.values(protocolConfig)?.[0];
+    }
+    if (!limitsConfig) {
+        throw new Error(`Rate Limit: Provider: "${provider}" has no tiers defined for ${protocol} in limits.json`);
+    }
+    return limitsConfig;
+};
+const parseLimits = (limits) => {
+    const _mapObject = (fn) => (o) => Object.fromEntries(Object.entries(o).map(fn));
+    const _formatProtocol = _mapObject((entry) => {
+        const [tierName, rest] = entry;
+        return [tierName.toLowerCase(), { ...rest }];
+    });
+    const _formatProvider = (ls) => {
+        const http = _formatProtocol(ls.http);
+        const ws = _formatProtocol(ls?.ws);
+        return { http, ws };
+    };
+    return _formatProvider(limits);
+};
+const calculateWSLimits = (providerLimit) => {
+    return {
+        connections: providerLimit.connections,
+        subscriptions: providerLimit.subscriptions,
+    };
+};
+const calculateRateLimit = (providerLimit) => {
+    let quota = providerLimit.rateLimit1m;
+    if (!quota && providerLimit?.rateLimit1h) {
+        quota = providerLimit?.rateLimit1h / 60;
+    }
+    else if (!quota && providerLimit?.rateLimit1s) {
+        quota = providerLimit?.rateLimit1s * 60;
+    }
+    return {
+        second: providerLimit?.rateLimit1s || (quota / 60) * exports.BURST_UNDEFINED_QUOTA_MULTIPLE,
+        minute: quota,
+    };
+};

package/examples/coingecko/batch-warming.d.ts

@@ -0,0 +1,2 @@
+import { AdapterEndpoint } from '../../adapter';
+export declare const batchEndpoint: AdapterEndpoint;

package/examples/coingecko/batch-warming.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.batchEndpoint = void 0;
+const batch_warming_1 = require("../../transports/batch-warming");
+const DEFAULT_URL = 'https://pro-api.coingecko.com/api/v3';
+const inputParameters = {
+    coinid: {
+        description: 'The CoinGecko id or array of ids of the coin(s) to query (Note: because of current limitations to use a dummy base will need to be supplied)',
+        required: false,
+    },
+    base: {
+        aliases: ['from', 'coin'],
+        description: 'The symbol or array of symbols of the currency to query',
+        required: true,
+    },
+    quote: {
+        aliases: ['to', 'market'],
+        description: 'The symbol of the currency to convert to',
+        required: true,
+    },
+};
+const batchEndpointTransport = new batch_warming_1.BatchWarmingTransport({
+    prepareRequest: (params, context) => {
+        return {
+            baseURL: DEFAULT_URL,
+            url: '/simple/price',
+            method: 'GET',
+            params: {
+                ids: [...new Set(params.map((p) => p.base))].join(','),
+                vs_currencies: [...new Set(params.map((p) => p.quote))].join(','),
+                x_cg_pro_api_key: context.adapterConfig.API_KEY,
+            },
+        };
+    },
+    parseResponse: (res) => {
+        const entries = [];
+        for (const [base, entry] of Object.entries(res.data)) {
+            for (const [quote, price] of Object.entries(entry)) {
+                entries.push({
+                    params: { base, quote },
+                    value: price,
+                });
+            }
+        }
+        return entries;
+    },
+});
+exports.batchEndpoint = {
+    name: 'batch',
+    transport: batchEndpointTransport,
+    inputParameters,
+};

package/examples/coingecko/index.d.ts

@@ -0,0 +1,2 @@
+import { Adapter } from '../../adapter';
+export declare const adapter: Adapter;

package/examples/coingecko/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adapter = void 0;
+const batch_warming_1 = require("./batch-warming");
+const rest_1 = require("./rest");
+exports.adapter = {
+    name: 'coingecko',
+    defaultEndpoint: 'batch',
+    endpoints: [rest_1.restEndpoint, batch_warming_1.batchEndpoint],
+};

package/examples/coingecko/rest.d.ts

@@ -0,0 +1,2 @@
+import { AdapterEndpoint } from '../../adapter';
+export declare const restEndpoint: AdapterEndpoint;

package/examples/coingecko/rest.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restEndpoint = void 0;
+const transports_1 = require("../../transports");
+const DEFAULT_URL = 'https://api.coingecko.com/api/v3';
+const inputParameters = {
+    coinid: {
+        description: 'The CoinGecko id or array of ids of the coin(s) to query (Note: because of current limitations to use a dummy base will need to be supplied)',
+        required: false,
+    },
+    base: {
+        aliases: ['from', 'coin'],
+        description: 'The symbol or array of symbols of the currency to query',
+        required: true,
+    },
+    quote: {
+        aliases: ['to', 'market'],
+        description: 'The symbol of the currency to convert to',
+        required: true,
+    },
+};
+const restEndpointTransport = new transports_1.RestTransport({
+    prepareRequest: (req) => {
+        return {
+            baseURL: DEFAULT_URL,
+            url: '/simple/price',
+            method: 'GET',
+            params: {
+                ids: req.requestContext.data.base,
+                vs_currencies: req.requestContext.data.quote,
+            },
+        };
+    },
+    parseResponse: (req, res) => {
+        return {
+            data: res.data,
+            statusCode: 200,
+            result: res.data[req.requestContext.data.base]?.[req.requestContext.data.quote],
+        };
+    },
+    options: {
+        coalescing: true,
+    },
+});
+exports.restEndpoint = {
+    name: 'rest',
+    aliases: ['qwe'],
+    transport: restEndpointTransport,
+    inputParameters,
+};

package/examples/ncfx/config/index.d.ts

@@ -0,0 +1,12 @@
+export declare const customSettings: {
+    readonly USERNAME: {
+        readonly description: "Username for the NCFX API";
+        readonly type: "string";
+        readonly required: true;
+    };
+    readonly PASSWORD: {
+        readonly description: "Password for the NCFX API";
+        readonly type: "string";
+        readonly required: true;
+    };
+};

package/examples/ncfx/config/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.customSettings = void 0;
+exports.customSettings = {
+    USERNAME: {
+        description: 'Username for the NCFX API',
+        type: 'string',
+        required: true,
+    },
+    PASSWORD: {
+        description: 'Password for the NCFX API',
+        type: 'string',
+        required: true,
+    },
+};

package/examples/ncfx/index.d.ts

@@ -0,0 +1,2 @@
+import { Adapter } from '../../adapter';
+export declare const adapter: Adapter;

package/examples/ncfx/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adapter = void 0;
+const config_1 = require("./config");
+const websocket_1 = require("./websocket");
+exports.adapter = {
+    name: 'ncfx',
+    endpoints: [websocket_1.webSocketEndpoint],
+    customSettings: config_1.customSettings,
+};

package/examples/ncfx/websocket.d.ts

@@ -0,0 +1,36 @@
+import { AdapterEndpoint } from '../../adapter';
+import { WebSocketTransport } from '../../transports/websocket';
+import { InputParameters } from '../../validation';
+interface AdapterRequestParams {
+    base: string;
+    quote: string;
+}
+export declare const inputParameters: InputParameters;
+interface ProviderMessage {
+    timestamp: string;
+    currencyPair: string;
+    bid: number;
+    offer: number;
+    mid: number;
+    changes: [
+        {
+            period: string;
+            change: number;
+            percentage: number;
+        }
+    ];
+}
+export declare const websocketTransport: WebSocketTransport<AdapterRequestParams, ProviderMessage[], {
+    readonly USERNAME: {
+        readonly description: "Username for the NCFX API";
+        readonly type: "string";
+        readonly required: true;
+    };
+    readonly PASSWORD: {
+        readonly description: "Password for the NCFX API";
+        readonly type: "string";
+        readonly required: true;
+    };
+}>;
+export declare const webSocketEndpoint: AdapterEndpoint;
+export {};