@chainlink/ccip-sdk 0.97.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainlink/ccip-sdk",
-  "version": "0.97.0",
+  "version": "1.1.0",
   "description": "SDK/Library to interact with CCIP",
   "author": "Chainlink devs",
   "license": "MIT",
@@ -8,6 +8,10 @@
     "type": "git",
     "url": "git+https://github.com/smartcontractkit/ccip-tools-ts.git"
   },
+  "homepage": "https://docs.chain.link/ccip/tools/sdk/",
+  "bugs": {
+    "url": "https://github.com/smartcontractkit/ccip-tools-ts/issues"
+  },
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -55,21 +59,21 @@
     "@depay/web3-mock": "^15.3.0",
     "@eslint/js": "^9.39.3",
     "@types/bn.js": "^5.2.0",
-    "@types/node": "25.3.0",
+    "@types/node": "25.3.5",
     "@types/yargs": "17.0.35",
     "eslint": "^9.39.3",
     "eslint-config-prettier": "10.1.8",
     "eslint-import-resolver-typescript": "4.4.4",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jsdoc": "^62.7.0",
+    "eslint-plugin-jsdoc": "^62.7.1",
     "eslint-plugin-prettier": "^5.5.5",
-    "eslint-plugin-tsdoc": "^0.5.0",
+    "eslint-plugin-tsdoc": "^0.5.2",
     "ethers-abitype": "1.0.3",
     "prettier": "^3.8.1",
     "prool": "^0.0.17",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.56.0",
-    "viem": "^2.46.2"
+    "typescript-eslint": "8.56.1",
+    "viem": "^2.47.0"
   },
   "dependencies": {
     "@aptos-labs/ts-sdk": "^5.2.1",
@@ -94,6 +98,6 @@
   },
   "overrides": {
     "bigint-buffer": "npm:@trufflesuite/bigint-buffer@1.1.10",
-    "axios": "^1.13.2"
+    "axios": "^1.13.5"
   }
 }

package/src/api/index.ts

@@ -2,24 +2,26 @@ import { memoize } from 'micro-memoize'
 import type { SetRequired } from 'type-fest'
 
 import {
+  CCIPApiClientNotAvailableError,
   CCIPHttpError,
   CCIPLaneNotFoundError,
   CCIPMessageIdNotFoundError,
   CCIPMessageNotFoundInTxError,
-  CCIPNotImplementedError,
   CCIPTimeoutError,
   CCIPUnexpectedPaginationError,
 } from '../errors/index.ts'
 import { HttpStatus } from '../http-status.ts'
+import { decodeMessageV1 } from '../messages.ts'
 import { decodeMessage } from '../requests.ts'
 import {
   type CCIPMessage,
   type CCIPRequest,
-  type ChainTransaction,
+  type ChainLog,
   type ExecutionInput,
-  type Log_,
+  type Lane,
   type Logger,
   type NetworkInfo,
+  type OffchainTokenData,
   type WithLogger,
   CCIPVersion,
   ChainFamily,
@@ -30,11 +32,13 @@ import { bigIntReviver, parseJson } from '../utils.ts'
 import type {
   APIErrorResponse,
   LaneLatencyResponse,
+  RawExecutionInputsResult,
   RawLaneLatencyResponse,
   RawMessageResponse,
   RawMessagesResponse,
   RawNetworkInfo,
 } from './types.ts'
+import { calculateManualExecProof } from '../execution.ts'
 
 export type { APICCIPRequestMetadata, APIErrorResponse, LaneLatencyResponse } from './types.ts'
 
@@ -44,6 +48,15 @@ export const DEFAULT_API_BASE_URL = 'https://api.ccip.chain.link'
 /** Default timeout for API requests in milliseconds */
 export const DEFAULT_TIMEOUT_MS = 30000
 
+/** SDK version string for telemetry header */
+// generate:nofail
+// `export const SDK_VERSION = '${require('./package.json').version}-${require('child_process').execSync('git rev-parse --short HEAD').toString().trim()}'`
+export const SDK_VERSION = '1.1.0-30c18a9'
+// generate:end
+
+/** SDK telemetry header name */
+export const SDK_VERSION_HEADER = 'X-SDK-Version'
+
 /**
  * Context for CCIPAPIClient initialization.
  */
@@ -126,7 +139,7 @@ export class CCIPAPIClient {
   static {
     CCIPAPIClient.fromUrl = memoize(
       (baseUrl?: string, ctx?: CCIPAPIClientContext) => new CCIPAPIClient(baseUrl, ctx),
-      { maxArgs: 1 },
+      { maxArgs: 1, transformKey: ([baseUrl]) => [baseUrl ?? DEFAULT_API_BASE_URL] },
     )
   }
 
@@ -136,10 +149,26 @@ export class CCIPAPIClient {
    * @param ctx - Optional context with logger and custom fetch
    */
   constructor(baseUrl?: string, ctx?: CCIPAPIClientContext) {
+    if (typeof baseUrl === 'boolean' || (baseUrl as unknown) === null)
+      throw new CCIPApiClientNotAvailableError({ context: { baseUrl } }) // shouldn't happen
     this.baseUrl = baseUrl ?? DEFAULT_API_BASE_URL
     this.logger = ctx?.logger ?? console
     this.timeoutMs = ctx?.timeoutMs ?? DEFAULT_TIMEOUT_MS
-    this._fetch = ctx?.fetch ?? globalThis.fetch
+    this._fetch = ctx?.fetch ?? globalThis.fetch.bind(globalThis)
+
+    this.getMessageById = memoize(this.getMessageById.bind(this), {
+      async: true,
+      expires: 4_000,
+      maxArgs: 1,
+      maxSize: 100,
+    })
+
+    this.getExecutionInput = memoize(this.getExecutionInput.bind(this), {
+      async: true,
+      expires: 4_000,
+      maxArgs: 1,
+      maxSize: 100,
+    })
   }
 
   /**
@@ -167,7 +196,13 @@ export class CCIPAPIClient {
     const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs)
 
     try {
-      return await this._fetch(url, { signal: controller.signal })
+      return await this._fetch(url, {
+        signal: controller.signal,
+        headers: {
+          'Content-Type': 'application/json',
+          [SDK_VERSION_HEADER]: `CCIP SDK v${SDK_VERSION}`,
+        },
+      })
     } catch (error) {
       if (error instanceof Error && error.name === 'AbortError') {
         throw new CCIPTimeoutError(operation, this.timeoutMs)
@@ -423,15 +458,109 @@ export class CCIPAPIClient {
   /**
    * Fetches the execution input for a given message by id.
    * @param messageId - The ID of the message to fetch the execution input for.
-   * @returns Either `{ encodedMessage, verifications }` or `{ message, offchainTokenData, ...proof }`, and offRamp
+   * @returns Either `{ encodedMessage, verifications }` or `{ message, offchainTokenData, ...proof }`, offRamp and lane
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  getExecutionInput(messageId: string): Promise<ExecutionInput & { offRamp: string }> {
-    throw new CCIPNotImplementedError(`CCIPAPIClient.getExecutionInput`)
-    // TODO: fetch (memoized) request with metadata from `getMessageById`
-    // TODO: if request doesn't contain averything needed (e.g. <v2.0), fetch `batch` and
-    // `offchainTokenData` from `/execution-input`
-    // TODO: if <v2.0, `calculateManualExecProof` and return `offRamp` and `input`
+  async getExecutionInput(messageId: string): Promise<ExecutionInput & Lane & { offRamp: string }> {
+    const url = `${this.baseUrl}/v2/messages/${encodeURIComponent(messageId)}/execution-inputs`
+
+    this.logger.debug(`CCIPAPIClient: GET ${url}`)
+
+    const response = await this._fetchWithTimeout(url, 'getExecutionInput')
+    if (!response.ok) {
+      // Try to parse structured error response from API
+      let apiError: APIErrorResponse | undefined
+      try {
+        apiError = parseJson<APIErrorResponse>(await response.text())
+      } catch {
+        // Response body not JSON, use HTTP status only
+      }
+
+      // 404 - Message not found
+      if (response.status === HttpStatus.NOT_FOUND) {
+        throw new CCIPMessageIdNotFoundError(messageId, {
+          context: apiError
+            ? {
+                apiErrorCode: apiError.error,
+                apiErrorMessage: apiError.message,
+              }
+            : undefined,
+        })
+      }
+
+      // Generic HTTP error for other cases
+      throw new CCIPHttpError(response.status, response.statusText, {
+        context: apiError
+          ? {
+              apiErrorCode: apiError.error,
+              apiErrorMessage: apiError.message,
+            }
+          : undefined,
+      })
+    }
+
+    const raw = JSON.parse(await response.text(), bigIntReviver) as RawExecutionInputsResult
+    this.logger.debug('getExecutionInput raw response:', raw)
+
+    const offRamp = raw.offramp
+    let lane: Lane
+    if ('encodedMessage' in raw) {
+      // CCIP 2.0 messages use MessageV1Codec, which is chain-independent serialization
+      const {
+        sourceChainSelector,
+        destChainSelector,
+        onRampAddress: onRamp,
+      } = decodeMessageV1(raw.encodedMessage)
+      return {
+        sourceChainSelector,
+        destChainSelector,
+        onRamp,
+        offRamp,
+        version: CCIPVersion.V2_0,
+        encodedMessage: raw.encodedMessage,
+        verifications: (raw.ccvData ?? []).map((ccvData, i) => ({
+          ccvData,
+          destAddress: raw.verifierAddresses[i]!,
+        })),
+      }
+    }
+
+    const messagesInBatch = raw.messageBatch.map(decodeMessage)
+    const message = messagesInBatch.find((message) => message.messageId === messageId)!
+    if ('onramp' in raw && raw.onramp && raw.version) {
+      lane = {
+        sourceChainSelector: raw.sourceChainSelector,
+        destChainSelector: raw.destChainSelector,
+        onRamp: raw.onramp,
+        version: raw.version as CCIPVersion,
+      }
+    } else {
+      ;({ lane } = await this.getMessageById(messageId))
+    }
+
+    const proof = calculateManualExecProof(messagesInBatch, lane, messageId, raw.merkleRoot, this)
+
+    const rawMessage = raw.messageBatch.find((message) => message.messageId === messageId)!
+    const offchainTokenData: OffchainTokenData[] = rawMessage.tokenAmounts.map(() => undefined)
+    if (rawMessage.usdcData?.status === 'complete')
+      offchainTokenData[0] = {
+        _tag: 'usdc',
+        message: rawMessage.usdcData.message_bytes_hex!,
+        attestation: rawMessage.usdcData.attestation!,
+      }
+    else if (rawMessage.lbtcData?.status === 'NOTARIZATION_STATUS_SESSION_APPROVED')
+      offchainTokenData[0] = {
+        _tag: 'lbtc',
+        message_hash: rawMessage.lbtcData.message_hash!,
+        attestation: rawMessage.lbtcData.attestation!,
+      }
+
+    return {
+      offRamp,
+      ...lane,
+      message,
+      offchainTokenData,
+      ...proof,
+    } as ExecutionInput & Lane & { offRamp: string }
   }
 
   /**
@@ -483,7 +612,7 @@ export class CCIPAPIClient {
     }
 
     // Build log from API data
-    const log: Log_ = {
+    const log: ChainLog = {
       transactionHash: sendTransactionHash,
       address: raw.onramp,
       data: { message: parseJson(text) },
@@ -493,11 +622,10 @@ export class CCIPAPIClient {
     }
 
     // Build tx from API data
-    const tx: ChainTransaction = {
+    const tx = {
       hash: log.transactionHash,
       timestamp: sendTimestamp_,
       from: origin,
-      logs: [log],
       blockNumber: Number(sendBlockNumber),
     }
     log.tx = tx

package/src/api/types.ts

@@ -182,3 +182,46 @@ export type APICCIPRequestMetadata = {
   /** Destination network metadata. */
   destNetworkInfo: NetworkInfo
 }
+
+// ============================================================================
+// GET /v2/messages/${messageId}/execution-inputs search endpoint types
+// ============================================================================
+
+/** Raw API response from GET /v2/messages/:messageId/execution-inputs */
+export type RawExecutionInputsResult = {
+  offramp: string
+} & (
+  | {
+      onramp: string
+      sourceChainSelector: bigint
+      destChainSelector: bigint
+      version: string
+    }
+  | object
+) &
+  (
+    | {
+        merkleRoot?: string
+        messageBatch: {
+          [key: string]: unknown
+          messageId: string
+          tokenAmounts: { token: string; amount: string }[]
+          usdcData?: {
+            status: 'pending_confirmations' | 'complete'
+            attestation?: string
+            message_bytes_hex?: string
+          }
+          lbtcData?: {
+            status: 'NOTARIZATION_STATUS_SESSION_APPROVED' | 'NOTARIZATION_STATUS_SESSION_PENDING'
+            attestation?: string
+            message_hash?: string
+          }
+        }[]
+      }
+    | {
+        encodedMessage: string
+        verificationComplete?: boolean
+        ccvData?: string[]
+        verifierAddresses: string[]
+      }
+  )

package/src/aptos/index.ts

@@ -56,14 +56,13 @@ import {
   type CCIPExecution,
   type CCIPMessage,
   type CCIPRequest,
+  type ChainLog,
   type ChainTransaction,
   type CommitReport,
   type ExecutionInput,
   type ExecutionReceipt,
   type Lane,
-  type Log_,
   type NetworkInfo,
-  type OffchainTokenData,
   type WithLogger,
   ChainFamily,
 } from '../types.ts'
@@ -236,7 +235,7 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
   }
 
   /** {@inheritDoc Chain.getLogs} */
-  async *getLogs(opts: LogFilter & { versionAsHash?: boolean }): AsyncIterableIterator<Log_> {
+  async *getLogs(opts: LogFilter & { versionAsHash?: boolean }): AsyncIterableIterator<ChainLog> {
     yield* streamAptosLogs(this, opts)
   }
 
@@ -415,7 +414,7 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
    * @returns Array of CommitReport or undefined if not valid.
    * @throws {@link CCIPAptosLogInvalidError} if log data format is invalid
    */
-  static decodeCommits({ data }: Pick<Log_, 'data'>, lane?: Lane): CommitReport[] | undefined {
+  static decodeCommits({ data }: Pick<ChainLog, 'data'>, lane?: Lane): CommitReport[] | undefined {
     if (!data || typeof data != 'object') throw new CCIPAptosLogInvalidError(data)
     const data_ = data as {
       blessed_merkle_roots: unknown[] | undefined
@@ -449,7 +448,7 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
    * @returns ExecutionReceipt or undefined if not valid.
    * @throws {@link CCIPAptosLogInvalidError} if log data format is invalid
    */
-  static decodeReceipt({ data }: Pick<Log_, 'data'>): ExecutionReceipt | undefined {
+  static decodeReceipt({ data }: Pick<ChainLog, 'data'>): ExecutionReceipt | undefined {
     if (!data || typeof data != 'object') throw new CCIPAptosLogInvalidError(data)
     const data_ = data as { message_id: string; state: number }
     if (!data_.message_id || !data_.state) return
@@ -553,12 +552,6 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
     return (await this.getMessagesInTx(await this.getTransaction(hash)))[0]!
   }
 
-  /** {@inheritDoc Chain.getOffchainTokenData} */
-  getOffchainTokenData(request: CCIPRequest): Promise<OffchainTokenData[]> {
-    // default offchain token data
-    return Promise.resolve(request.message.tokenAmounts.map(() => undefined))
-  }
-
   /**
    * {@inheritDoc Chain.generateUnsignedExecute}
    * @throws {@link CCIPAptosExtraArgsV2RequiredError} if message missing EVMExtraArgsV2 fields

package/src/aptos/logs.ts

@@ -15,7 +15,7 @@ import {
   CCIPLogsWatchRequiresStartError,
   CCIPTopicsInvalidError,
 } from '../errors/index.ts'
-import type { Log_ } from '../types.ts'
+import type { ChainLog } from '../types.ts'
 import { sleep } from '../utils.ts'
 
 const DEFAULT_POLL_INTERVAL = 5e3
@@ -241,7 +241,7 @@ async function* fetchEventsBackward(
 export async function* streamAptosLogs(
   ctx: { provider: Aptos },
   opts: LogFilter & { versionAsHash?: boolean },
-): AsyncGenerator<Log_> {
+): AsyncGenerator<ChainLog> {
   const limit = 100
   if (!opts.address || !opts.address.includes('::')) throw new CCIPAptosAddressModuleRequiredError()
   if (opts.topics?.length !== 1 || typeof opts.topics[0] !== 'string')