[OPDATA-4082] Add Coinpaprika State adapter

[paul-chain]

Description

Adds a new Coinpaprika State external adapter that streams state_price via Server-Sent Events (SSE).
See package README for full details

Changes

• New package: @chainlink/coinpaprika-state-adapter
• Endpoint: coinpaprika-state (alias: state)
• Transport: single-connection SSE with:
  • pair batching & dynamic reconnect on pair-set change
  • JSON parsing with malformed-event tolerance
  • graceful shutdown & reconnection backoff with jitter

Sample Input and Output

Sample Input

{
  "data": {
    "base": "LUSD",
    "quote": "USD",
    "endpoint": "coinpaprika-state"
  }
}

Using the alias state

{
  "data": {
    "base": "LUSD", 
    "quote": "USD",
    "endpoint": "state"
  }
}

Without endpoint (uses default)

{
  "data": {
    "base": "LUSD",
    "quote": "USD"
  }
}

Sample Output

{
  "data": {
    "result": 1.000979,
    "timestamp": 1758888503
  },
  "statusCode": 200,
  "result": 1.000979,
  "timestamps": {
    "providerDataRequestedUnixMs": 1758888508939,
    "providerDataReceivedUnixMs": 1758888508939,
    "providerIndicatedTimeUnixMs": 1758888503000
  },
  "meta": {
    "adapterName": "COINPAPRIKA_STATE",
    "metrics": {
      "feedId": "{\"base\":\"lusd\",\"quote\":\"usd\"}"
    }
  }
}

Example cURL Requests

Using the primary endpoint coinpaprika-state

curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"data":{"base":"LUSD","quote":"USD","endpoint":"coinpaprika-state"}}'

Using the alias state

curl -X POST http://localhost:8080 \
    -H "Content-Type: application/json" \
    -d '{"data": {"base": "LUSD", "quote": "USD", "endpoint": "state"}}'

Without endpoint (uses default)

curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"data": {"base": "LUSD", "quote": "USD"}}'

Steps to Test

1. Navigate to the root of the external-adapters-js repo
2. Build the adapter: yarn workspace @chainlink/coinpaprika-state-adapter build
3. Run tests:

• Integration test: yarn test packages/sources/coinpaprika-state/test/integration/adapter.test.ts
• Unit test: yarn test packages/sources/coinpaprika-state/test/unit/sse.test.ts

Quality Assurance

• If a new adapter was made, or an existing one was modified so that its environment variables have changed, update the relevant infra-k8s configuration file.
• If a new adapter was made, or an existing one was modified so that its environment variables have changed, update the relevant adapter-secrets configuration file or update the soak testing blacklist.
• If a new adapter was made, or a new endpoint was added, update the test-payload.json file with relevant requests.
• The branch naming follows git flow (feature/x, chore/x, release/x, hotfix/x, fix/x) or is created from Jira.
• This is related to a maximum of one Jira story or GitHub issue.
• Types are safe (avoid TypeScript/TSLint features like any and disable, instead use more specific types).
• All code changes have 100% unit and integration test coverage. If testing is not applicable or too difficult to justify doing, the reasoning should be documented explicitly in the PR.

[changeset-bot]

🦋 Changeset detected

Latest commit: 944e7d9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@chainlink/coinpaprika-state-adapter	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[karen-stepanyan]

any reason why this is not a new endpoint on existing coinpaprika EA ?

[paul-chain]

Updated to use existing EA with new endpoint

[alejoberardino]

saw this pr randomly, there's an sse transport in the framework, what's the particular reason this adapter needs a custom one?

[paul-chain]

@alejoberardino I investigated SseTransport but found it's designed around the usual EventSource/GET model (and optional separate sub/unsub/keepalive calls). The current design of Coinpaprika State API instead opens a single SSE connection via POST with a JSON body containing all pairs and expects reconnects when the pair set changes. Given that shape, SubscriptionTransport is a cleaner fit for batching pairs and managing one shared connection + reconnection logic.

[mxiao-cll]

Can you provide a sample input param and sample output

[mmcallister-cll]

can this ever be called?

[mmcallister-cll]

Just wondering, did you try extending StreamingTransport and implementing streamHandler?
At a glance it seems like that would manage subscriptions for you rather than rewriting havePairsChanged.

BTW: Coinmetrics is a different WS-based EA that switches URLs for every new subscription, not sure if there is any inspiration to pull from it: https://github.com/smartcontractkit/external-adapters-js/blob/main/packages/sources/coinmetrics/src/transport/lwba.ts#L62-L75

[mmcallister-cll]

is this used?

[mmcallister-cll]

is there no library that can do some of this for us?

[mmcallister-cll]

are 2 logs needed or is 1 debug enough?

[mmcallister-cll]

isn't this a duplicate log in backgroundHandler?

[mmcallister-cll]

maybe extract this section into an sseConnectionErrorHandler function for clarity since this is already a long function

[mmcallister-cll]

504 or 502?

[mmcallister-cll]

is the (first stream kept open) part correct here?

[mmcallister-cll]

could investigate whether it's worth including this in a superclass over the requester (something like AbortableRequester). Might not be worth the effort but could save some of this complexity for setting/unsetting the AbortController

[mmcallister-cll]

should we be doing this here or just let the next backgroundHandler invocation start a new connection?

In fact, could also extract the management of timing these connections into some SSEConnectionManager class or similar