@chainlink/ccip-sdk 0.96.0 → 1.0.0

package/src/execution.ts

@@ -1,23 +1,13 @@
 import { memoize } from 'micro-memoize'
 
-import type { Chain, ChainStatic } from './chain.ts'
+import type { Chain } from './chain.ts'
 import {
   CCIPMerkleRootMismatchError,
   CCIPMessageNotInBatchError,
   CCIPOffRampNotFoundError,
 } from './errors/index.ts'
 import { Tree, getLeafHasher, proofFlagsToBits } from './hasher/index.ts'
-import {
-  type CCIPCommit,
-  type CCIPExecution,
-  type CCIPMessage,
-  type CCIPRequest,
-  type CCIPVersion,
-  type ExecutionReport,
-  type Lane,
-  type WithLogger,
-  ExecutionState,
-} from './types.ts'
+import type { CCIPMessage, CCIPVersion, Lane, WithLogger } from './types.ts'
 
 /**
  * Pure/sync function to calculate/generate OffRamp.executeManually report for messageIds
@@ -28,6 +18,38 @@ import {
  * @param merkleRoot - Optional merkleRoot of the CommitReport, for validation
  * @param ctx - Context for logging
  * @returns ManualExec report arguments
+ * @throws CCIPMessageNotInBatchError - When the messageId is not found in the provided batch
+ * @throws CCIPMerkleRootMismatchError - When calculated merkle root doesn't match the provided one
+ *
+ * @remarks
+ * This is a pure/sync function that performs no I/O - all data must be pre-fetched.
+ * It builds a merkle tree from the messages, generates a proof for the target messageId,
+ * and optionally validates against the provided merkleRoot.
+ *
+ * The returned proof can be used with `execute` to manually execute a stuck message.
+ *
+ * @example
+ * ```typescript
+ * import { calculateManualExecProof, EVMChain } from '@chainlink/ccip-sdk'
+ *
+ * // Fetch the request and all messages in its batch
+ * const request = (await source.getMessagesInTx(txHash))[0]
+ * const verifications = await dest.getVerifications({ offRamp, request })
+ * const messages = await source.getMessagesInBatch(request, commit.report)
+ *
+ * // Calculate proof for manual execution
+ * const proof = calculateManualExecProof(
+ *   messages,
+ *   request.lane,
+ *   request.message.messageId,
+ *   commit.report.merkleRoot
+ * )
+ * console.log('Merkle root:', proof.merkleRoot)
+ * console.log('Proofs:', proof.proofs)
+ * ```
+ * @see {@link discoverOffRamp} - Find the OffRamp for manual execution
+ * @see {@link execute} - Execute the report on destination chain
+ * @see {@link generateUnsignedExecute} - Build unsigned execution tx
  **/
 export function calculateManualExecProof<V extends CCIPVersion = CCIPVersion>(
   messagesInBatch: readonly CCIPMessage<V>[],
@@ -35,7 +57,7 @@ export function calculateManualExecProof<V extends CCIPVersion = CCIPVersion>(
   messageId: string,
   merkleRoot?: string,
   ctx?: WithLogger,
-): Omit<ExecutionReport, 'offchainTokenData' | 'message'> {
+) {
   const hasher = getLeafHasher(lane, ctx)
 
   const msgIdx = messagesInBatch.findIndex((message) => message.messageId === messageId)
@@ -64,6 +86,30 @@ export function calculateManualExecProof<V extends CCIPVersion = CCIPVersion>(
   }
 }
 
+/**
+ * Discover the OffRamp address for a given OnRamp and destination chain.
+ * Results are memoized for performance.
+ *
+ * @param source - Source chain instance.
+ * @param dest - Destination chain instance.
+ * @param onRamp - OnRamp contract address on source chain.
+ * @param ctx - Optional context with logger.
+ * @returns OffRamp address on destination chain.
+ * @throws CCIPOffRampNotFoundError - When no matching OffRamp is found for the OnRamp
+ * @example
+ * ```typescript
+ * import { discoverOffRamp, EVMChain } from '@chainlink/ccip-sdk'
+ *
+ * const source = await EVMChain.fromUrl('https://rpc.sepolia.org')
+ * const dest = await EVMChain.fromUrl('https://rpc.fuji.avax.network')
+ *
+ * const offRamp = await discoverOffRamp(source, dest, onRampAddress)
+ * console.log('OffRamp on destination:', offRamp)
+ * ```
+ * @see {@link calculateManualExecProof} - Use with OffRamp for manual execution
+ * @see {@link execute} - Execute on destination chain
+ * @see {@link getExecutionReceipts} - Check execution status
+ */
 export const discoverOffRamp = memoize(
   async function discoverOffRamp_(
     source: Chain,
@@ -77,42 +123,76 @@ export const discoverOffRamp = memoize(
       dest.network.chainSelector,
     )
     for (const offRamp of sourceOffRamps) {
-      let destOnRamp: string
+      let destOnRamps
       try {
-        destOnRamp = await source.getOnRampForOffRamp(offRamp, dest.network.chainSelector)
-      } catch {
-        logger.debug('discoverOffRamp: skipping offRamp', offRamp, '(no valid source chain config)')
-        continue
-      }
-      const destRouter = await dest.getRouterForOnRamp(destOnRamp, source.network.chainSelector)
-      const destOffRamps = await dest.getOffRampsForRouter(destRouter, source.network.chainSelector)
-      for (const offRamp of destOffRamps) {
-        let offRampsOnRamp: string
-        try {
-          offRampsOnRamp = await dest.getOnRampForOffRamp(offRamp, source.network.chainSelector)
-        } catch {
-          logger.debug(
-            'discoverOffRamp: skipping dest offRamp',
-            offRamp,
-            '(no valid source chain config)',
-          )
-          continue
-        }
+        destOnRamps = await source.getOnRampsForOffRamp(offRamp, dest.network.chainSelector)
+      } catch (err) {
         logger.debug(
-          'discoverOffRamp: found, from',
-          {
-            sourceOnRamp: onRamp,
-            sourceRouter,
-            sourceOffRamps,
-            destOnRamp,
-            destOffRamps,
-            offRampsOnRamp,
-          },
-          '=',
+          'discoverOffRamp: skipping offRamp',
           offRamp,
+          '(no valid source chain config)',
+          err,
+        )
+        continue
+      }
+      for (const destOnRamp of destOnRamps) {
+        const destRouter = await dest.getRouterForOnRamp(destOnRamp, source.network.chainSelector)
+        const destOffRamps = await dest.getOffRampsForRouter(
+          destRouter,
+          source.network.chainSelector,
         )
-        if (offRampsOnRamp === onRamp) {
-          return offRamp
+        for (const offRamp of destOffRamps) {
+          let offRampsOnRamps
+          try {
+            offRampsOnRamps = await dest.getOnRampsForOffRamp(offRamp, source.network.chainSelector)
+          } catch (err) {
+            logger.debug(
+              'discoverOffRamp: skipping dest offRamp',
+              offRamp,
+              '(no valid source chain config)',
+              err,
+            )
+            continue
+          }
+          for (const offRampsOnRamp of offRampsOnRamps) {
+            logger.debug(
+              'discoverOffRamp: found, from',
+              {
+                sourceOnRamp: onRamp,
+                sourceRouter,
+                sourceOffRamps,
+                destOnRamp,
+                destOffRamps,
+                offRampsOnRamp,
+              },
+              '=',
+              offRamp,
+            )
+            for (const offRamp of destOffRamps) {
+              const offRampsOnRamps = await dest.getOnRampsForOffRamp(
+                offRamp,
+                source.network.chainSelector,
+              )
+              for (const offRampsOnRamp of offRampsOnRamps) {
+                logger.debug(
+                  'discoverOffRamp: found, from',
+                  {
+                    sourceOnRamp: onRamp,
+                    sourceRouter,
+                    sourceOffRamps,
+                    destOnRamp,
+                    destOffRamps,
+                    offRampsOnRamps,
+                  },
+                  '=',
+                  offRamp,
+                )
+                if (offRampsOnRamp === onRamp) {
+                  return offRamp
+                }
+              }
+            }
+          }
         }
       }
     }
@@ -123,44 +203,3 @@ export const discoverOffRamp = memoize(
       [source.network.chainSelector, dest.network.chainSelector, onRamp] as const,
   },
 )
-
-/**
- * Generic implementation for fetching ExecutionReceipts for given requests.
- * If more than one request is given, may yield them interleaved.
- * Completes as soon as there's no more work to be done.
- *
- * Two possible behaviors:
- * - if `startBlock|startTime` is given, pages forward from that block up;
- *   completes when success (final) receipt is found for all requests (or reach latest block)
- * - otherwise, pages backwards and returns only the most recent receipt per request;
- *   completes when receipts for all requests were seen
- *
- * @param dest - Provider to page through.
- * @param offRamp - OffRamp contract address.
- * @param request - CCIP request to search executions for.
- * @param commit - Optional commit info to narrow down search.
- * @param hints - Optional hints (e.g., `page` for getLogs pagination range).
- */
-export async function* getExecutionReceipts(
-  dest: Chain,
-  offRamp: string,
-  request: CCIPRequest,
-  commit?: CCIPCommit,
-  hints?: { page?: number },
-): AsyncGenerator<CCIPExecution> {
-  const onlyLast = !commit?.log.blockNumber && !request.tx.timestamp // backwards
-  for await (const log of dest.getLogs({
-    startBlock: commit?.log.blockNumber,
-    startTime: request.tx.timestamp,
-    address: offRamp,
-    topics: ['ExecutionStateChanged'],
-    ...hints,
-  })) {
-    const receipt = (dest.constructor as ChainStatic).decodeReceipt(log)
-    if (!receipt || receipt.messageId !== request.message.messageId) continue
-
-    const timestamp = log.tx?.timestamp ?? (await dest.getBlockTimestamp(log.blockNumber))
-    yield { receipt, log, timestamp }
-    if (onlyLast || receipt.state === ExecutionState.Success) break
-  }
-}

package/src/extra-args.ts

@@ -9,7 +9,7 @@ export const EVMExtraArgsV1Tag = id('CCIP EVMExtraArgsV1').substring(0, 10) as '
 /** Tag identifier for EVMExtraArgsV2 encoding. */
 export const EVMExtraArgsV2Tag = id('CCIP EVMExtraArgsV2').substring(0, 10) as '0x181dcf10'
 /** Tag identifier for GenericExtraArgsV3 encoding (tightly packed binary format). */
-export const GenericExtraArgsV3Tag = '0x302326cb' as const
+export const GenericExtraArgsV3Tag = id('CCIP GenericExtraArgsV3').substring(0, 10) as '0xa69dd4aa'
 /** Tag identifier for SVMExtraArgsV1 encoding. */
 export const SVMExtraArgsV1Tag = id('CCIP SVMExtraArgsV1').substring(0, 10) as '0x1f3b3aba'
 /** Tag identifier for SuiExtraArgsV1 encoding. */
@@ -145,6 +145,7 @@ export type ExtraArgs =
  * Encodes extra arguments for CCIP messages.
  * The args are *to* a dest network, but are encoded as a message *from* this source chain.
  * E.g. Solana uses Borsh to encode extraArgs in its produced requests, even those targeting EVM.
+ *
  * @param args - Extra arguments to encode
  * @param from - Source chain family for encoding format (defaults to EVM)
  * @returns Encoded extra arguments as hex string
@@ -152,12 +153,16 @@ export type ExtraArgs =
  *
  * @example
  * ```typescript
+ * import { encodeExtraArgs } from '@chainlink/ccip-sdk'
+ *
  * const encoded = encodeExtraArgs({
  *   gasLimit: 200_000n,
  *   allowOutOfOrderExecution: true,
  * })
- * // Returns: '0x181dcf10...'
+ * console.log('Encoded:', encoded) // '0x181dcf10...'
  * ```
+ *
+ * @see {@link decodeExtraArgs} - Decode extra arguments from bytes
  */
 export function encodeExtraArgs(args: ExtraArgs, from: ChainFamily = ChainFamily.EVM): string {
   const chain = supportedChains[from]
@@ -175,11 +180,16 @@ export function encodeExtraArgs(args: ExtraArgs, from: ChainFamily = ChainFamily
  *
  * @example
  * ```typescript
+ * import { decodeExtraArgs } from '@chainlink/ccip-sdk'
+ *
  * const decoded = decodeExtraArgs('0x181dcf10...')
  * if (decoded?._tag === 'EVMExtraArgsV2') {
- *   console.log(decoded.gasLimit, decoded.allowOutOfOrderExecution)
+ *   console.log('Gas limit:', decoded.gasLimit)
+ *   console.log('Out of order:', decoded.allowOutOfOrderExecution)
  * }
  * ```
+ *
+ * @see {@link encodeExtraArgs} - Encode extra arguments to bytes
  */
 export function decodeExtraArgs(
   data: BytesLike,

package/src/gas.ts

@@ -4,6 +4,7 @@ import type { Chain } from './chain.ts'
 import {
   CCIPContractTypeInvalidError,
   CCIPMethodUnsupportedError,
+  CCIPOnRampRequiredError,
   CCIPTokenDecimalsInsufficientError,
 } from './errors/index.ts'
 import { discoverOffRamp } from './execution.ts'
@@ -50,11 +51,34 @@ export type EstimateReceiveExecutionOpts = {
 
 /**
  * Estimate CCIP gasLimit needed to execute a request on a contract receiver.
- * @param opts - Options for estimation: source and dest chains, router or ramp address, and message
- * @returns Estimated gasLimit.
+ *
+ * @param opts - {@link EstimateReceiveExecutionOpts} for estimation
+ * @returns Estimated gasLimit
+ *
  * @throws {@link CCIPMethodUnsupportedError} if dest chain doesn't support estimation
  * @throws {@link CCIPContractTypeInvalidError} if routerOrRamp is not a valid contract type
  * @throws {@link CCIPTokenDecimalsInsufficientError} if dest token has insufficient decimals
+ *
+ * @example
+ * ```typescript
+ * import { estimateReceiveExecution, EVMChain } from '@chainlink/ccip-sdk'
+ *
+ * const source = await EVMChain.fromUrl('https://rpc.sepolia.org')
+ * const dest = await EVMChain.fromUrl('https://rpc.fuji.avax.network')
+ *
+ * const gasLimit = await estimateReceiveExecution({
+ *   source,
+ *   dest,
+ *   routerOrRamp: '0xRouter...',
+ *   message: {
+ *     sender: '0x...',
+ *     receiver: '0x...',
+ *     data: '0x...',
+ *     tokenAmounts: [],
+ *   },
+ * })
+ * console.log('Estimated gas:', gasLimit)
+ * ```
  */
 export async function estimateReceiveExecution({
   source,
@@ -78,7 +102,9 @@ export async function estimateReceiveExecution({
       if (!tnv[0].includes('OffRamp'))
         throw new CCIPContractTypeInvalidError(routerOrRamp, tnv[2], ['OffRamp'])
       offRamp = routerOrRamp
-      onRamp = await dest.getOnRampForOffRamp(offRamp, source.network.chainSelector)
+      const onRamps = await dest.getOnRampsForOffRamp(offRamp, source.network.chainSelector)
+      if (!onRamps.length) throw new CCIPOnRampRequiredError()
+      onRamp = onRamps[onRamps.length - 1]!
     } catch {
       throw sourceErr // re-throw original error
     }

package/src/index.ts

@@ -13,7 +13,12 @@ export type {
   CCIPAPIClientContext,
   LaneLatencyResponse,
 } from './api/index.ts'
-export { CCIPAPIClient, DEFAULT_API_BASE_URL } from './api/index.ts'
+export {
+  CCIPAPIClient,
+  DEFAULT_API_BASE_URL,
+  SDK_VERSION,
+  SDK_VERSION_HEADER,
+} from './api/index.ts'
 
 export type {
   ApiRetryConfig,
@@ -41,16 +46,18 @@ export {
   encodeExtraArgs,
 } from './extra-args.ts'
 export { estimateReceiveExecution } from './gas.ts'
+export { getOffchainTokenData } from './offchain.ts'
 export { decodeMessage, getMessagesForSender, sourceToDestTokenAddresses } from './requests.ts'
 export {
-  type CCIPCommit,
   type CCIPExecution,
   type CCIPMessage,
   type CCIPRequest,
+  type CCIPVerifications,
+  type ChainLog,
   type ChainTransaction,
   type CommitReport,
+  type ExecutionInput,
   type ExecutionReceipt,
-  type ExecutionReport,
   type Lane,
   type Logger,
   type MessageInput,

package/src/offchain.ts

@@ -1,56 +1,79 @@
-import { keccak256 } from 'ethers'
+import { type BytesLike, dataLength, dataSlice, getBytes, toNumber } from 'ethers'
+import type { PickDeep } from 'type-fest'
 
 import {
   CCIPLbtcAttestationNotApprovedError,
   CCIPLbtcAttestationNotFoundError,
   CCIPUsdcAttestationError,
 } from './errors/index.ts'
-import { NetworkType } from './types.ts'
+import { parseSourceTokenData } from './evm/messages.ts'
+import { type CCIPRequest, type OffchainTokenData, type WithLogger, NetworkType } from './types.ts'
+import { networkInfo } from './utils.ts'
 
 const CIRCLE_API_URL = {
-  mainnet: 'https://iris-api.circle.com/v1',
-  testnet: 'https://iris-api-sandbox.circle.com/v1',
+  mainnet: 'https://iris-api.circle.com',
+  testnet: 'https://iris-api-sandbox.circle.com',
 }
 
 type CctpAttestationResponse =
   | { error: 'string' }
-  | { status: 'pending_confirmations' }
-  | { status: 'complete'; attestation: string }
-
-const LOMBARD_API_URL = {
-  mainnet: 'https://mainnet.prod.lombard.finance',
-  testnet: 'https://gastald-testnet.prod.lombard.finance',
-}
-
-type LombardAttestation =
-  | { status: 'NOTARIZATION_STATUS_SESSION_APPROVED'; message_hash: string; attestation: string }
-  | { status: string; message_hash: string }
-type LombardAttestationsResponse = { attestations: Array<LombardAttestation> }
+  | {
+      messages: {
+        status: 'pending_confirmations' | 'complete'
+        eventNonce?: string
+        attestation: string
+        message: string
+      }[]
+    }
 
 /**
- * Returns the USDC attestation for a given MessageSent Log
- * https://developers.circle.com/stablecoins/reference/getattestation
+ * Returns the USDC attestation for a given tokenAmount.extraData and txHash
+ * https://developers.circle.com/cctp/quickstarts/transfer-usdc-ethereum-to-arc#3-3-retrieve-attestation
  *
- * @param message - payload of USDC MessageSent(bytes message) event
+ * @param opts - CCTPv2 options
  * @param networkType - network type (mainnet or testnet)
- * @returns USDC/CCTP attestation bytes
+ * @returns USDC/CCTP attestation and message
  */
 export async function getUsdcAttestation(
-  message: string,
+  opts: {
+    /** CCTP sourceDomain */
+    sourceDomain: number
+    /** CCTP burn eventNonce */
+    nonce: number
+    /** burn txHash, same as CCIP request */
+    txHash: string
+  },
   networkType: NetworkType,
-): Promise<string> {
-  const msgHash = keccak256(message)
-
+): Promise<{ attestation: string; message: string }> {
+  const { sourceDomain, nonce, txHash } = opts
   const circleApiBaseUrl =
     networkType === NetworkType.Mainnet ? CIRCLE_API_URL.mainnet : CIRCLE_API_URL.testnet
-  const res = await fetch(`${circleApiBaseUrl}/attestations/${msgHash}`)
+  const res = await fetch(
+    `${circleApiBaseUrl}/v2/messages/${sourceDomain}?transactionHash=${txHash}`,
+  )
   const json = (await res.json()) as CctpAttestationResponse
-  if (!('status' in json) || json.status !== 'complete' || !json.attestation) {
-    throw new CCIPUsdcAttestationError(msgHash, json)
+  let att
+  if ('messages' in json) {
+    att = json.messages.find((m) => m.status === 'complete' && m.eventNonce === nonce.toString())
   }
-  return json.attestation
+  if (!att?.message) throw new CCIPUsdcAttestationError(txHash, json, { context: opts })
+  return att
+}
+
+const LOMBARD_API_URL = {
+  mainnet: 'https://mainnet.prod.lombard.finance',
+  testnet: 'https://gastald-testnet.prod.lombard.finance',
 }
 
+type LombardAttestation =
+  | {
+      status: 'NOTARIZATION_STATUS_SESSION_APPROVED'
+      message_hash: string
+      attestation: string
+    }
+  | { status: string; message_hash: string }
+type LombardAttestationsResponse = { attestations: Array<LombardAttestation> }
+
 /**
  * Returns the LBTC attestation for a given payload hash
  *
@@ -86,3 +109,77 @@ export async function getLbtcAttestation(
   }
   return attestation
 }
+
+/**
+ * Fetch CCIPv1 offchain token data for USDC and LBTC tokenAmounts
+ * @param request - CCIPRequest containing tx.hash and message
+ * @returns Promise resolving to an OffchainTokenData for each tokenAmount
+ */
+export async function getOffchainTokenData(
+  request: PickDeep<CCIPRequest, 'tx.hash' | `message`>,
+  { logger = console }: WithLogger = {},
+): Promise<OffchainTokenData[]> {
+  const { networkType } = networkInfo(request.message.sourceChainSelector)
+
+  function looksUsdcData(extraData: BytesLike) {
+    if (dataLength(extraData) !== 64) return
+    // USDCTokenPool's extraData is a packed `SourceTokenDataPayloadV1{uint64 nonce, uint32 sourceDomain}`,
+    // which we need to query CCTPv2 (by sourceDomain and txHash) and to filter by nonce among messages,
+    // if more than one in tx
+    let nonce, sourceDomain
+    try {
+      // those toNumber conversions throw early in case the bytearray don't look like small numbers
+      nonce = toNumber(dataSlice(extraData, 0, 32))
+      sourceDomain = toNumber(dataSlice(extraData, 32, 32 + 32))
+      return { nonce, sourceDomain } // maybe USDC
+    } catch {
+      // not USDC
+    }
+  }
+
+  function looksLbtcData(extraData: BytesLike) {
+    // LBTC returns `message_hash`/`payloadHash` directly as `bytes32 extraData`
+    if (
+      dataLength(extraData) === 32 &&
+      getBytes(extraData, 'extraData').filter(Boolean).length > 20 // looks like a hash
+    )
+      return true
+  }
+
+  return Promise.all(
+    request.message.tokenAmounts.map(async (tokenAmount, i) => {
+      let extraData
+      if ('extraData' in tokenAmount) {
+        extraData = tokenAmount.extraData
+      } else if ('sourceTokenData' in request.message) {
+        // v1.2..v1.5
+        if (dataLength(request.message.sourceTokenData[i]!) === 64) {
+          extraData = request.message.sourceTokenData[i]
+        } else {
+          ;({ extraData } = parseSourceTokenData(request.message.sourceTokenData[i]!))
+        }
+      }
+      if (!extraData) return
+      const usdcOpts = looksUsdcData(extraData)
+      if (usdcOpts) {
+        try {
+          const usdcAttestation = await getUsdcAttestation(
+            { ...usdcOpts, txHash: request.tx.hash },
+            networkType,
+          )
+          return { _tag: 'usdc', extraData, ...usdcAttestation }
+        } catch (err) {
+          // maybe not a USDC transfer, or not ready
+          logger.warn(`❌ CCTP: Failed to fetch attestation for message:`, request.message, err)
+        }
+      } else if (looksLbtcData(extraData)) {
+        try {
+          const lbtcAttestation = await getLbtcAttestation(extraData, networkType)
+          return { _tag: 'lbtc', extraData, ...lbtcAttestation }
+        } catch (err) {
+          logger.warn(`❌ LBTC: Failed to fetch attestation for message:`, extraData, err)
+        }
+      }
+    }),
+  )
+}