DOCSEARCHbyAlgolia
Submit Docs

Chainlink External Adapters JS

repository·main·Indexed 43 days ago

https://github.com/smartcontractkit/external-adapters-js

A collection of external adapters for Chainlink (version 1.411.0) used to fetch token balances across blockchain networks such as Solana, Stellar, and Litecoin. Includes composite adapters like CALCULATED_PRICE for mathematical operations on source adapter values, as well as specialized adapters for GLV_TOKEN, GM_TOKEN, GMX_TOKENS, and GOLD. Provides Grafana dashboards (ea-detailed and ea-overview) for visualizing adapter metrics.

Tokens
324.1K
Snippets
1.2K
Records
1.6K
Agent score
54%

What's inside Chainlink External Adapters JS

  1. Overview of Chainlink Source External Adapters

    main
    The packages/sources directory contains a collection of Chainlink Source External Adapters. These adapters are designed to fetch data from various third-party APIs and services to be used as data sources for Chainlink nodes. Each adapter is specialized for a specific provider (e.g., CoinGecko, Coinbase, Etherscan) or a specific type of data (e.g., token balances, market hours, or proof of reserves).

  3. Available Grafana dashboards

    main

    The repository provides two primary dashboard types for visualizing external adapter metrics via Grafana:

    • ea-detailed: Provides detailed insights into a single external adapter at a time.
    • ea-overview: Provides a high-level overview of all external adapters simultaneously.

    Both dashboards are written in jsonnet using the grafonnet library.

  5. What is the Error Backoff Middleware?

    main
    The Error Backoff Middleware is a mechanism designed to prevent overwhelming a target service during periods of instability. It tracks the number of failed requests occurring within a rolling one-minute window. If the error threshold is met, the middleware implements a backoff strategy to reduce the frequency of requests, allowing the downstream service time to recover.

  7. How the Streams Adapter Runtime works

    main

    The Streams Adapter Runtime is a high-throughput Go-based system that runs alongside a JavaScript adapter process. It is designed to optimize request handling by using an in-memory cache and asynchronous subscriptions.

    Architecture

    The runtime consists of two cooperating processes managed by supervisord:

    1. Go streams runtime (packages/streams-adapter): Handles the HTTP API, manages the in-memory cache, and provides a Redis-compatible ingestion server.
    2. JavaScript adapter runtime: Manages communication with data providers and handles the subscription lifecycle.

    Request Flow

    1. A client sends a POST / request to the Go runtime.
    2. Parameters are canonicalized using aliases from endpoint_aliases.json.
    3. The runtime checks the in-memory cache:
      • Cache Hit: Returns the cached observation immediately with a 200 status.
      • Cache Miss: Triggers an asynchronous subscription request to the JS adapter and returns a 504 error, instructing the caller to retry.
    4. The JS adapter writes updates to the Redis-compatible server (via the EVAL path), which populates the cache.
    5. Subsequent requests for the same data result in cache hits.

  9. Understand Cache Key Derivation

    main

    The cache key is constructed by concatenating the cache group key with the SHA1 hash of the input object using a : symbol.

    Cache Group Key Format: {EA_NAME}:{CACHE_KEY_GROUP} (e.g., BINANCE:CUSTOM_KEY).

    Key Derivation Logic:

    • The input object is hashed using SHA1.
    • By default, certain keys are ignored during hashing: ['id', 'maxAge', 'meta', 'rateLimitMaxAge', 'debug', 'metricsMeta'].
    • You can add more ignored keys via CACHE_KEY_IGNORED_PROPS (comma-delimited).

    Per-item maxAge:

    • The maxAge input argument sets the TTL for a specific item.
    • If maxAge is not set or is 0, the global CACHE_MAX_AGE is used.
    • To bypass the cache for a specific request, set maxAge: -1 (or any value < 0).

  10. Understand hardcoded logic in the Finage External Adapter

    main

    The Finage External Adapter (EA) contains custom hardcoded logic that operates independently of the standard overrides.json configuration. This logic affects how specific assets are routed to different transport protocols (like REST) and how certain currency pairs are calculated.

    When working with Finage, be aware that:

    1. Transport Routing: Certain assets in both the forex and crypto endpoints are hardcoded to use REST instead of other available transport methods.
    2. Forex Inversion: Many forex assets quoted in USD are automatically inversed by the adapter. A specific internal map defines which assets are excluded from this inversion logic.

  11. Use the Balance factory to query address balances

    main

    The Balance factory is used to query the balance of specific addresses for a given coin and chain. It accepts a list of address objects and returns an array of balance information including the address, balance amount, coin, and chain.

    ### Input

- `dataPath`: Optional path where to find the addresses array, defaults to `result`
- `confirmations`: Optional confirmations param, defaults to `6`

- `addresses`: A list of addresses to query

```json
[
    {
        "address": "Address to query",
        "coin": "Optional currency to query, defaults to btc.",
        "chain": "Optional chain to query, defaults to mainnet."
    },
    ...
  ]
]

    Output

    [
    {
        "address": "string",
        "balance": 0,
        "coin": "string",
        "chain": "string",
        "warning?": "string"
    },
    ...
]

  12. How middlewares work in the External Adapter Bootstrap framework

    main

    The Bootstrap framework wraps the data provider's specific execute function with multiple middlewares to improve efficiency (reducing API credits, networking traffic, and CPU usage).

    Execution Lifecycle:

    1. Initialization: Middlewares are initialized to wrap the incoming request.
    2. Runtime Execution: The execution of middlewares happens in reverse order of their initialization.
    3. Post-Execution: If a middleware contains awaited code, that code executes in the original order once the execute function has returned.

    Key middlewares include:

    • Caching: Supports Local cache (LRU) and Redis. Local cache can serve as a fallback.
    • Cache Warming: For REST requests, warming is triggered via the redux architecture; WebSockets use a dedicated warming mechanism.
    • Batching: Works in conjunction with caching and cache warming to handle batch endpoints.
    • Rate Limiting: Implemented via Express middleware (throttling/delaying), a Burst Limit redux middleware (rejecting requests exceeding thresholds), and a Rate Limit redux middleware (adjusting TTL based on monthly limits).
    • Error Backoff: Rejects incoming requests for a specified time window if the Data Provider (DP) returns errors beyond a certain threshold.