@lifi/sdk 4.8.2 → 4.9.0

package/src/client/createClient.ts

@@ -1,5 +1,6 @@
 import type { ChainId, ChainType, ExtendedChain } from '@lifi/types'
 import type {
+  RPCUrls,
   SDKBaseConfig,
   SDKClient,
   SDKConfig,
@@ -20,12 +21,38 @@ export function createClient(options: SDKConfig): SDKClient {
     checkPackageUpdates(name, version)
   }
 
-  const { providers, ...configOptions } = options
+  const { providers, rpcUrls, ...configOptions } = options
+
+  // Role entries split once, here: the config keeps plain read lists, so
+  // everything that reads `config.rpcUrls` sees `string[]` as before.
+  const readRpcUrls: RPCUrls = {}
+  const writeRpcUrls: RPCUrls = {}
+  const bundleRpcUrls: RPCUrls = {}
+  let hasRoles = false
+  for (const key in rpcUrls) {
+    const chainId = Number(key) as ChainId
+    const entry = rpcUrls[chainId]
+    if (Array.isArray(entry)) {
+      readRpcUrls[chainId] = entry
+    } else if (entry) {
+      hasRoles = true
+      if (entry.read) {
+        readRpcUrls[chainId] = entry.read
+      }
+      if (entry.write?.length) {
+        writeRpcUrls[chainId] = entry.write
+      }
+      if (entry.bundle?.length) {
+        bundleRpcUrls[chainId] = entry.bundle
+      }
+    }
+  }
 
   const _config: SDKBaseConfig = {
     ...configOptions,
     apiUrl: configOptions?.apiUrl ?? 'https://li.quest/v1',
-    rpcUrls: configOptions?.rpcUrls ?? {},
+    // Plain lists only: the caller's own object, exactly as before.
+    rpcUrls: hasRoles ? readRpcUrls : ((rpcUrls ?? {}) as RPCUrls),
     debug: configOptions?.debug ?? false,
     preloadChains: configOptions?.preloadChains ?? true,
     integrator: configOptions?.integrator ?? 'lifi-sdk',
@@ -78,6 +105,12 @@ export function createClient(options: SDKConfig): SDKClient {
       }
       return chainRpcUrls
     },
+    async getWriteRpcUrlsByChainId(chainId: ChainId) {
+      return writeRpcUrls[chainId] ?? []
+    },
+    async getBundleRpcUrlsByChainId(chainId: ChainId) {
+      return bundleRpcUrls[chainId] ?? []
+    },
   }
 
   function extend<TClient extends SDKClient>(

package/src/index.ts

@@ -97,6 +97,8 @@ export type {
   RouteExecutionDictionary,
   RouteExtended,
   RPCUrls,
+  RPCUrlsByRole,
+  RPCUrlsConfig,
   SDKBaseConfig,
   SDKClient,
   SDKConfig,

package/src/types/core.ts

@@ -38,11 +38,55 @@ export interface SDKBaseConfig {
   storage?: SDKStorage
 }
 
-export interface SDKConfig extends Partial<Omit<SDKBaseConfig, 'integrator'>> {
+export interface SDKConfig
+  extends Partial<Omit<SDKBaseConfig, 'integrator' | 'rpcUrls'>> {
   integrator: string
+  /**
+   * Per chain, one list for reads and sends, or lists by role. The client
+   * keeps the read lists in `config.rpcUrls` and serves the write and bundle
+   * lists through `getWriteRpcUrlsByChainId` and `getBundleRpcUrlsByChainId`.
+   */
+  rpcUrls?: RPCUrlsConfig
   providers?: SDKProvider[]
 }
 
+/**
+ * RPC URLs for one chain, split by what they are used for.
+ */
+export interface RPCUrlsByRole {
+  /**
+   * Reads: balances, simulation and confirmation. Unset, the chain's own RPC
+   * URLs serve reads, as for a chain with no `rpcUrls` entry.
+   */
+  read?: string[]
+  /**
+   * Sends. Unset or empty, the read URLs send as well. While `write` is set,
+   * nothing is sent through the read URLs: when `bundle` is unset, the write
+   * URLs that support bundles also submit bundles, and with none of them, a
+   * route that needs a bundle fails.
+   *
+   * Only `@lifi/sdk-provider-solana` uses this today; other providers ignore
+   * it.
+   */
+  write?: string[]
+  /**
+   * Bundle submissions (Jito `sendBundle`). Unset, empty, or with no URL that
+   * supports bundles, the write URLs that do submit them. While `bundle` or
+   * `write` is set, bundles never go to the read URLs.
+   *
+   * Only `@lifi/sdk-provider-solana` uses this today; other providers ignore
+   * it.
+   */
+  bundle?: string[]
+}
+
+/**
+ * The `rpcUrls` option of `createClient`: per chain, either one list for reads
+ * and sends, or lists by role.
+ */
+export type RPCUrlsConfig = Partial<Record<ChainId, string[] | RPCUrlsByRole>>
+
+/** RPC URL lists per chain. `client.config.rpcUrls` holds the read lists. */
 export type RPCUrls = Partial<Record<ChainId, string[]>>
 
 export interface SDKProvider {
@@ -78,6 +122,20 @@ export interface SDKClient {
   getChainById(chainId: ChainId): Promise<ExtendedChain>
   getRpcUrls(): Promise<RPCUrls>
   getRpcUrlsByChainId(chainId: ChainId): Promise<string[]>
+  /**
+   * The chain's dedicated write RPC URLs (`rpcUrls[chainId].write`). Empty
+   * when the chain has none.
+   *
+   * Optional so clients from other SDK versions, and hand-written ones, still
+   * satisfy `SDKClient`. Providers treat a missing method as no write list.
+   */
+  getWriteRpcUrlsByChainId?(chainId: ChainId): Promise<string[]>
+  /**
+   * The chain's dedicated bundle RPC URLs (`rpcUrls[chainId].bundle`). Empty
+   * when the chain has none. Optional for the same reason as
+   * `getWriteRpcUrlsByChainId`.
+   */
+  getBundleRpcUrlsByChainId?(chainId: ChainId): Promise<string[]>
 }
 
 export interface StepExecutorOptions {

package/src/utils/withDedupe.ts

@@ -20,26 +20,144 @@ export class LruMap<value = unknown> extends Map<string, value> {
   }
 }
 
+type Caller = {
+  resolve: (value: any) => void
+  reject: (error: unknown) => void
+}
+
+type InFlight = {
+  promise: Promise<any>
+  /** Absent when the first caller had no signal: then nothing can abort it. */
+  controller?: AbortController | undefined
+  /** Callers with a signal that are still waiting, once the first one joins. */
+  callers?: Set<Caller> | undefined
+  /** A caller without a signal joined, so the request must run to the end. */
+  pinned: boolean
+}
+
 /** @internal */
-const promiseCache = /*#__PURE__*/ new LruMap<Promise<any>>(8192)
+const promiseCache = /*#__PURE__*/ new LruMap<InFlight>(8192)
 
 type WithDedupeOptions = {
   enabled?: boolean | undefined
   id?: string | undefined
+  /** Lets this caller leave a shared request without aborting it for others. */
+  signal?: AbortSignal | undefined
 }
 
-/** Deduplicates in-flight promises. */
+/**
+ * Deduplicates in-flight promises.
+ *
+ * When the first caller passes a signal, `fn` receives the signal to hand on
+ * to its request. A caller that aborts leaves the shared request at once; the
+ * request itself is aborted only when every caller has aborted. The next
+ * caller then starts a new request, so `fn` should pass the signal on: a run
+ * that ignores it keeps going alongside the new one.
+ */
+export function withDedupe<T>(
+  fn: (signal?: AbortSignal) => Promise<T>,
+  options: WithDedupeOptions
+): Promise<T>
 export function withDedupe<T>(
   fn: () => Promise<T>,
-  { enabled = true, id }: WithDedupeOptions
+  options: WithDedupeOptions & { signal?: undefined }
+): Promise<T>
+export function withDedupe<T>(
+  fn: (signal?: AbortSignal) => Promise<T>,
+  { enabled = true, id, signal }: WithDedupeOptions
 ): Promise<T> {
   if (!enabled || !id) {
-    return fn()
+    return fn(signal)
+  }
+  if (signal?.aborted) {
+    return Promise.reject(abortReason(signal))
+  }
+  let inFlight = promiseCache.get(id)
+  if (!inFlight) {
+    const controller = signal ? new AbortController() : undefined
+    const promise = fn(controller?.signal).finally(() => evict(id, promise))
+    inFlight = { promise, controller, pinned: false }
+    promiseCache.set(id, inFlight)
+  }
+  return join<T>(id, inFlight, signal)
+}
+
+function join<T>(
+  id: string,
+  inFlight: InFlight,
+  signal: AbortSignal | undefined
+): Promise<T> {
+  if (!signal) {
+    inFlight.pinned = true
+    return inFlight.promise
   }
-  if (promiseCache.get(id)) {
-    return promiseCache.get(id)!
+  const callers = inFlight.callers ?? subscribe(inFlight)
+  return new Promise<T>((resolve, reject) => {
+    // Stop listening before settling, so a later abort cannot reach the request.
+    const caller: Caller = {
+      resolve: (value) => {
+        signal.removeEventListener('abort', leave)
+        resolve(value)
+      },
+      reject: (error) => {
+        signal.removeEventListener('abort', leave)
+        reject(error)
+      },
+    }
+    const leave = () => {
+      // `leave` can run without the event, so the listener is not always gone.
+      signal.removeEventListener('abort', leave)
+      callers.delete(caller)
+      const reason = abortReason(signal)
+      reject(reason)
+      if (!inFlight.pinned && callers.size === 0) {
+        // A caller arriving now must start a new request, not join this one.
+        evict(id, inFlight.promise)
+        inFlight.controller?.abort(reason)
+      }
+    }
+    callers.add(caller)
+    signal.addEventListener('abort', leave, { once: true })
+    // `fn` runs before this listener exists and may have aborted the signal.
+    if (signal.aborted) {
+      leave()
+    }
+  })
+}
+
+/**
+ * Hands the result to the callers with a signal, through one reaction per
+ * request, so a caller that leaves holds nothing here. It is added only when
+ * the first such caller joins: a request shared only by callers without a
+ * signal gets no handler of ours, and a failure they all ignore is still
+ * reported as an unhandled rejection.
+ */
+function subscribe(inFlight: InFlight): Set<Caller> {
+  const callers = new Set<Caller>()
+  inFlight.callers = callers
+  inFlight.promise.then(
+    (value) => {
+      for (const caller of callers) {
+        caller.resolve(value)
+      }
+    },
+    (error) => {
+      for (const caller of callers) {
+        caller.reject(error)
+      }
+    }
+  )
+  return callers
+}
+
+/** Drops the entry for `id` only while it still holds this request. */
+function evict(id: string, promise: Promise<unknown>): void {
+  if (promiseCache.get(id)?.promise === promise) {
+    promiseCache.delete(id)
   }
-  const promise = fn().finally(() => promiseCache.delete(id))
-  promiseCache.set(id, promise)
-  return promise
 }
+
+/** Older runtimes and polyfills can abort a signal without a `reason`. */
+const abortReason = (signal: AbortSignal): unknown =>
+  signal.reason ??
+  Object.assign(new Error('This operation was aborted'), { name: 'AbortError' })

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/sdk'
-export const version = '4.8.2'
+export const version = '4.9.0'