@chainlink/ccip-sdk 0.91.0 → 0.92.0

package/src/aptos/logs.ts

@@ -8,7 +8,17 @@ import {
 import { memoize } from 'micro-memoize'
 
 import type { LogFilter } from '../chain.ts'
+import {
+  CCIPAptosAddressModuleRequiredError,
+  CCIPAptosTopicInvalidError,
+  CCIPAptosTransactionTypeUnexpectedError,
+  CCIPLogsWatchRequiresFinalityError,
+  CCIPLogsWatchRequiresStartError,
+} from '../errors/index.ts'
 import type { Log_ } from '../types.ts'
+import { sleep } from '../utils.ts'
+
+const DEFAULT_POLL_INTERVAL = 5e3
 
 const eventToHandler = {
   CCIPMessageSent: 'OnRampState/ccip_message_sent_events',
@@ -30,29 +40,24 @@ export async function getUserTxByVersion(
     ledgerVersion: version,
   })
   if (tx.type !== TransactionResponseType.User)
-    throw new Error(`Unexpected transaction type="${tx.type}"`)
+    throw new CCIPAptosTransactionTypeUnexpectedError(tx.type)
   return tx
 }
 
 /**
  * Gets the timestamp for a given transaction version.
  * @param provider - Aptos provider instance.
- * @param version - Version number or 'finalized'.
- * @returns Timestamp in seconds.
+ * @param version - Positive version number, negative block depth finality, or 'finalized'.
+ * @returns Epoch timestamp in seconds.
  */
 export async function getVersionTimestamp(
   provider: Aptos,
   version: number | 'finalized',
 ): Promise<number> {
-  if (version === 'finalized') {
-    const info = await provider.getLedgerInfo()
-    const tx = await provider.getTransactionByVersion({
-      ledgerVersion: +info.ledger_version,
-    })
-    return +(tx as UserTransactionResponse).timestamp / 1e6
-  }
-  const tx = await getUserTxByVersion(provider, version)
-  return +tx.timestamp / 1e6
+  if (typeof version !== 'number') version = 0
+  if (version <= 0) version = +(await provider.getLedgerInfo()).ledger_version + version
+  const tx = await provider.getTransactionByVersion({ ledgerVersion: version })
+  return +(tx as UserTransactionResponse).timestamp / 1e6
 }
 
 type ResEvent = AptosEvent & { version: string }
@@ -84,12 +89,16 @@ async function binarySearchFirst(
 }
 
 async function* fetchEventsForward(
-  provider: Aptos,
-  opts: LogFilter,
+  { provider }: { provider: Aptos },
+  opts: LogFilter & { pollInterval?: number },
   eventHandlerField: string,
   stateAddr: string,
   limit = 100,
 ): AsyncGenerator<ResEvent> {
+  if (opts.watch && typeof opts.endBlock === 'number' && opts.endBlock > 0)
+    throw new CCIPLogsWatchRequiresFinalityError(opts.endBlock)
+  opts.endBlock ||= 'latest'
+
   const fetchBatch = memoize(
     async (start?: number) => {
       const { data }: { data: ResEvent[] } = await getAptosFullNode({
@@ -101,7 +110,7 @@ async function* fetchEventsForward(
       if (!start) fetchBatch.cache.set([+data[0].sequence_number], Promise.resolve(data))
       return data
     },
-    { maxArgs: 1, maxSize: 100 },
+    { maxArgs: 1, maxSize: 100, async: true },
   )
 
   const initialBatch = await fetchBatch()
@@ -124,8 +133,25 @@ async function* fetchEventsForward(
     start = end - limit + 1
   }
 
-  let first = true
-  for (; start < end; start += limit) {
+  let notAfter =
+    typeof opts.endBlock !== 'number'
+      ? undefined
+      : opts.endBlock < 0
+        ? memoize(
+            async () =>
+              +(await provider.getLedgerInfo()).ledger_version + (opts.endBlock as number),
+            {
+              async: true,
+              maxArgs: 0,
+              expires: opts.pollInterval || DEFAULT_POLL_INTERVAL,
+            },
+          )
+        : opts.endBlock
+
+  let first = true,
+    catchedUp = false
+  while (opts.watch || !catchedUp) {
+    const lastReq = performance.now()
     const data = await fetchBatch(start)
     if (
       first &&
@@ -139,17 +165,40 @@ async function* fetchEventsForward(
       })
       data.splice(0, actualStart - 1)
     }
+
+    if (!first && catchedUp && typeof opts.endBlock === 'number' && opts.endBlock < 0)
+      notAfter = +(await provider.getLedgerInfo()).ledger_version + opts.endBlock
+
     first = false
+
     for (const ev of data) {
       if (opts.startBlock && +ev.version < opts.startBlock) continue
-      if (opts.endBlock && +ev.version > opts.endBlock) return
+      // there may be an unknown interval between yields, so we support memoized negative finality
+      if (
+        notAfter &&
+        +ev.version > (typeof notAfter === 'function' ? await notAfter() : notAfter)
+      ) {
+        catchedUp = true
+        break
+      }
+      const start_: number = +ev.sequence_number
+      start = start_ + 1
       yield ev
     }
+    catchedUp ||= start >= end
+    if (opts.watch && catchedUp) {
+      let break$ = sleep(
+        Math.max((opts.pollInterval || DEFAULT_POLL_INTERVAL) - (performance.now() - lastReq), 1),
+      ).then(() => false)
+      if (opts.watch instanceof Promise)
+        break$ = Promise.race([break$, opts.watch.then(() => true)])
+      if (await break$) break
+    }
   }
 }
 
 async function* fetchEventsBackward(
-  provider: Aptos,
+  { provider }: { provider: Aptos },
   opts: LogFilter,
   eventHandlerField: string,
   stateAddr: string,
@@ -157,6 +206,12 @@ async function* fetchEventsBackward(
 ): AsyncGenerator<ResEvent> {
   let start
   let cont = true
+  const notAfter =
+    typeof opts.endBlock !== 'number'
+      ? undefined
+      : opts.endBlock < 0
+        ? +(await provider.getLedgerInfo()).ledger_version + opts.endBlock
+        : opts.endBlock
   do {
     const { data } = await getAptosFullNode<object, ResEvent[]>({
       aptosConfig: provider.config,
@@ -170,7 +225,7 @@ async function* fetchEventsBackward(
     else start = Math.max(+data[0].sequence_number - limit, 1)
 
     for (const ev of data.reverse()) {
-      if (opts.endBlock && +ev.version > opts.endBlock) continue
+      if (notAfter && +ev.version > notAfter) continue
       if (+ev.sequence_number <= 1) cont = false
       yield ev
     }
@@ -184,20 +239,19 @@ async function* fetchEventsBackward(
  * @returns Async generator of log entries.
  */
 export async function* streamAptosLogs(
-  provider: Aptos,
+  ctx: { provider: Aptos },
   opts: LogFilter & { versionAsHash?: boolean },
 ): AsyncGenerator<Log_> {
   const limit = 100
-  if (!opts.address || !opts.address.includes('::'))
-    throw new Error('address with module is required')
+  if (!opts.address || !opts.address.includes('::')) throw new CCIPAptosAddressModuleRequiredError()
   if (opts.topics?.length !== 1 || typeof opts.topics[0] !== 'string')
-    throw new Error('single string topic required')
+    throw new CCIPAptosTopicInvalidError()
   let eventHandlerField = opts.topics[0]
   if (!eventHandlerField.includes('/')) {
     eventHandlerField = (eventToHandler as Record<string, string>)[eventHandlerField]
-    if (!eventHandlerField) throw new Error(`Unknown topic event handler="${opts.topics[0]}"`)
+    if (!eventHandlerField) throw new CCIPAptosTopicInvalidError(opts.topics[0])
   }
-  const [stateAddr] = await provider.view<[string]>({
+  const [stateAddr] = await ctx.provider.view<[string]>({
     payload: {
       function: `${opts.address}::get_state_address` as `0x${string}::${string}::get_state_address`,
     },
@@ -205,10 +259,12 @@ export async function* streamAptosLogs(
 
   let eventsIter
   if (opts.startBlock || opts.startTime) {
-    eventsIter = fetchEventsForward(provider, opts, eventHandlerField, stateAddr, limit)
+    eventsIter = fetchEventsForward(ctx, opts, eventHandlerField, stateAddr, limit)
+  } else if (opts.watch) {
+    throw new CCIPLogsWatchRequiresStartError()
   } else {
     // backwards, just paginate down to lowest sequence number
-    eventsIter = fetchEventsBackward(provider, opts, eventHandlerField, stateAddr, limit)
+    eventsIter = fetchEventsBackward(ctx, opts, eventHandlerField, stateAddr, limit)
   }
 
   let topics
@@ -221,7 +277,7 @@ export async function* streamAptosLogs(
       blockNumber: +ev.version,
       transactionHash: opts?.versionAsHash
         ? `${ev.version}`
-        : (await getUserTxByVersion(provider, +ev.version)).hash,
+        : (await getUserTxByVersion(ctx.provider, +ev.version)).hash,
       data: ev.data as Record<string, unknown>,
     }
   }

package/src/aptos/token.ts

@@ -1,6 +1,7 @@
 import type { Aptos } from '@aptos-labs/ts-sdk'
 
 import type { TokenInfo } from '../chain.ts'
+import { CCIPError } from '../errors/CCIPError.ts'
 
 /**
  * Retrieves token metadata (symbol and decimals) from Aptos.
@@ -152,5 +153,8 @@ export async function getTokenInfo(provider: Aptos, token: string): Promise<Toke
     }
   }
 
-  throw lastErr ?? new Error(`Could not view token info for ${token}`)
+  throw CCIPError.from(
+    lastErr ?? `Could not view token info for ${token}`,
+    'TOKEN_POOL_INFO_NOT_FOUND',
+  )
 }

package/src/aptos/types.ts

@@ -78,12 +78,12 @@ export function serializeExecutionReport(
 ): Uint8Array {
   const message = execReport.message
   return ExecutionReportCodec.serialize({
-    sourceChainSelector: message.header.sourceChainSelector,
-    messageId: getBytes(message.header.messageId),
-    headerSourceChainSelector: message.header.sourceChainSelector,
-    destChainSelector: message.header.destChainSelector,
-    sequenceNumber: message.header.sequenceNumber,
-    nonce: message.header.nonce,
+    sourceChainSelector: message.sourceChainSelector,
+    messageId: getBytes(message.messageId),
+    headerSourceChainSelector: message.sourceChainSelector,
+    destChainSelector: message.destChainSelector,
+    sequenceNumber: message.sequenceNumber,
+    nonce: message.nonce,
     sender: getAddressBytes(message.sender),
     data: getBytes(message.data),
     receiver: getAddressBytes(message.receiver),

package/src/chain.ts

@@ -1,9 +1,10 @@
 import type { BytesLike } from 'ethers'
-import type { PickDeep } from 'type-fest'
+import type { PickDeep, SetOptional } from 'type-fest'
 
 import type { UnsignedAptosTx } from './aptos/types.ts'
 import { fetchCommitReport } from './commits.ts'
-import type { UnsignedEVMTx } from './evm/index.ts'
+import { CCIPChainFamilyMismatchError, CCIPTransactionNotFinalizedError } from './errors/index.ts'
+import type { UnsignedEVMTx } from './evm/types.ts'
 import type {
   EVMExtraArgsV1,
   EVMExtraArgsV2,
@@ -13,6 +14,7 @@ import type {
 } from './extra-args.ts'
 import type { LeafHasher } from './hasher/common.ts'
 import type { UnsignedSolanaTx } from './solana/types.ts'
+import type { UnsignedTONTx } from './ton/types.ts'
 import {
   type AnyMessage,
   type CCIPCommit,
@@ -43,9 +45,13 @@ export type LogFilter = {
   /** Starting Unix timestamp (inclusive). */
   startTime?: number
   /** Ending block number (inclusive). */
-  endBlock?: number
-  /** Optional hint signature for end of iteration. */
+  endBlock?: number | 'finalized' | 'latest'
+  /** Solana: optional hint txHash for end of iteration. */
   endBefore?: string
+  /** watch mode: polls for new logs after fetching since start (required), until endBlock finality tag
+   *  (e.g. endBlock=finalized polls only finalized logs); can be a promise to cancel loop
+   */
+  watch?: boolean | Promise<unknown>
   /** Contract address to filter logs by. */
   address?: string
   /** Topics to filter logs by. */
@@ -100,6 +106,7 @@ export type UnsignedTx = {
   [ChainFamily.EVM]: UnsignedEVMTx
   [ChainFamily.Solana]: UnsignedSolanaTx
   [ChainFamily.Aptos]: UnsignedAptosTx
+  [ChainFamily.TON]: UnsignedTONTx
   [ChainFamily.Sui]: never // TODO
 }
 
@@ -117,7 +124,11 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
    */
   constructor(network: NetworkInfo, { logger = console }: WithLogger = {}) {
     if (network.family !== (this.constructor as ChainStatic).family)
-      throw new Error(`Invalid network family for ${this.constructor.name}: ${network.family}`)
+      throw new CCIPChainFamilyMismatchError(
+        this.constructor.name,
+        (this.constructor as ChainStatic).family,
+        network.family,
+      )
     this.network = network as NetworkInfo<F>
     this.logger = logger
   }
@@ -132,7 +143,7 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
 
   /**
    * Fetch the timestamp of a given block
-   * @param block - block number or 'finalized'
+   * @param block - positive block number, negative finality depth or 'finalized' tag
    * @returns timestamp of the block, in seconds
    */
   abstract getBlockTimestamp(block: number | 'finalized'): Promise<number>
@@ -142,6 +153,49 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
    * @returns generic transaction details
    */
   abstract getTransaction(hash: string): Promise<ChainTransaction>
+  /**
+   * Confirm a log tx is finalized or wait for it to be finalized
+   * Throws if it isn't included (e.g. a reorg)
+   */
+  async waitFinalized(
+    {
+      log,
+      tx,
+    }: SetOptional<
+      PickDeep<
+        CCIPRequest,
+        | `log.${'address' | 'blockNumber' | 'transactionHash' | 'topics' | 'tx.timestamp'}`
+        | 'tx.timestamp'
+      >,
+      'tx'
+    >,
+    finality: number | 'finalized' = 'finalized',
+    cancel$?: Promise<unknown>,
+  ): Promise<true> {
+    const timestamp = log.tx?.timestamp ?? tx?.timestamp
+    if (!timestamp || Date.now() / 1e3 - timestamp > 60) {
+      // only try to fetch tx if request is old enough (>60s)
+      const [trans, finalizedTs] = await Promise.all([
+        this.getTransaction(log.transactionHash),
+        this.getBlockTimestamp(finality),
+      ])
+      if (trans.timestamp <= finalizedTs) return true
+    }
+    for await (const l of this.getLogs({
+      address: log.address,
+      startBlock: log.blockNumber,
+      endBlock: finality,
+      topics: [log.topics[0]],
+      watch: cancel$ ?? true,
+    })) {
+      if (l.transactionHash === log.transactionHash) {
+        return true
+      } else if (l.blockNumber > log.blockNumber) {
+        break
+      }
+    }
+    throw new CCIPTransactionNotFinalizedError(log.transactionHash)
+  }
   /**
    * An async generator that yields logs based on the provided options.
    * @param opts - Options object containing:
@@ -189,7 +243,7 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
   abstract fetchAllMessagesInBatch<
     R extends PickDeep<
       CCIPRequest,
-      'lane' | `log.${'topics' | 'address' | 'blockNumber'}` | 'message.header.sequenceNumber'
+      'lane' | `log.${'topics' | 'address' | 'blockNumber'}` | 'message.sequenceNumber'
     >,
   >(
     request: R,
@@ -374,8 +428,8 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
    **/
   async fetchCommitReport(
     commitStore: string,
-    request: PickDeep<CCIPRequest, 'lane' | 'message.header.sequenceNumber' | 'tx.timestamp'>,
-    hints?: { startBlock?: number; page?: number },
+    request: PickDeep<CCIPRequest, 'lane' | 'message.sequenceNumber' | 'tx.timestamp'>,
+    hints?: Pick<LogFilter, 'page' | 'watch'> & { startBlock?: number },
   ): Promise<CCIPCommit> {
     return fetchCommitReport(this, commitStore, request, hints)
   }
@@ -390,9 +444,9 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
    */
   async *fetchExecutionReceipts(
     offRamp: string,
-    request: PickDeep<CCIPRequest, 'lane' | 'message.header.messageId' | 'tx.timestamp'>,
+    request: PickDeep<CCIPRequest, 'lane' | 'message.messageId' | 'tx.timestamp'>,
     commit?: CCIPCommit,
-    hints?: { page?: number },
+    hints?: Pick<LogFilter, 'page' | 'watch'>,
   ): AsyncIterableIterator<CCIPExecution> {
     const onlyLast = !commit?.log.blockNumber && !request.tx.timestamp // backwards
     for await (const log of this.getLogs({
@@ -403,7 +457,7 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
       ...hints,
     })) {
       const receipt = (this.constructor as ChainStatic).decodeReceipt(log)
-      if (!receipt || receipt.messageId !== request.message.header.messageId) continue
+      if (!receipt || receipt.messageId !== request.message.messageId) continue
 
       const timestamp = log.tx?.timestamp ?? (await this.getBlockTimestamp(log.blockNumber))
       yield { receipt, log, timestamp }
@@ -514,6 +568,23 @@ export type ChainStatic<F extends ChainFamily = ChainFamily> = Function & {
    * @returns Address in this chain family's format
    */
   getAddress(bytes: BytesLike): string
+  /**
+   * Validates a transaction hash format for this chain family
+   */
+  isTxHash(v: unknown): v is string
+  /**
+   * Format an address for human-friendly display.
+   * Defaults to getAddress if not overridden.
+   * @param address - Address string in any recognized format
+   * @returns Human-friendly address string for display
+   */
+  formatAddress?(address: string): string
+  /**
+   * Format a transaction hash for human-friendly display.
+   * @param hash - Transaction hash string
+   * @returns Human-friendly hash string for display
+   */
+  formatTxHash?(hash: string): string
   /**
    * Create a leaf hasher for this dest chain and lane
    * @param lane - source, dest and onramp lane info

package/src/commits.ts

@@ -1,6 +1,7 @@
 import type { PickDeep } from 'type-fest'
 
-import type { Chain, ChainStatic } from './chain.ts'
+import type { Chain, ChainStatic, LogFilter } from './chain.ts'
+import { CCIPCommitNotFoundError } from './errors/index.ts'
 import { type CCIPCommit, type CCIPRequest, CCIPVersion } from './types.ts'
 
 /**
@@ -19,10 +20,10 @@ export async function fetchCommitReport(
   commitStore: string,
   {
     lane,
-    message: { header },
+    message,
     tx: { timestamp: requestTimestamp },
-  }: PickDeep<CCIPRequest, 'lane' | 'message.header.sequenceNumber' | 'tx.timestamp'>,
-  hints?: { startBlock?: number; page?: number },
+  }: PickDeep<CCIPRequest, 'lane' | 'message.sequenceNumber' | 'tx.timestamp'>,
+  hints?: Pick<LogFilter, 'page' | 'watch'> & { startBlock?: number },
 ): Promise<CCIPCommit> {
   for await (const log of dest.getLogs({
     ...hints,
@@ -30,14 +31,25 @@ export async function fetchCommitReport(
     address: commitStore,
     topics: [lane.version < CCIPVersion.V1_6 ? 'ReportAccepted' : 'CommitReportAccepted'],
   })) {
-    const report = (dest.constructor as ChainStatic).decodeCommits(log, lane)?.[0]
-    if (!report || report.maxSeqNr < header.sequenceNumber) continue
-    // since we walk forward from some startBlock/startTime, give up if we find a newer report
-    if (report.minSeqNr > header.sequenceNumber) break
-    return { report, log }
+    const reports = (dest.constructor as ChainStatic).decodeCommits(log, lane)
+    if (!reports) continue
+    const validReports = reports.filter((r) => {
+      if (!r || r.maxSeqNr < message.sequenceNumber) return
+      // we could give up since we walk forward from some startBlock/startTime, but there might be some out-of-order logs
+      if (r.minSeqNr > message.sequenceNumber) return
+      return true
+    })
+
+    if (validReports.length === 0) continue
+
+    return {
+      log,
+      report: validReports[0],
+    }
   }
 
-  throw new Error(
-    `Could not find commit after ${hints?.startBlock ?? requestTimestamp} for sequenceNumber=${header.sequenceNumber}`,
+  throw new CCIPCommitNotFoundError(
+    hints?.startBlock ?? String(requestTimestamp),
+    message.sequenceNumber,
   )
 }

package/src/errors/CCIPError.ts

@@ -0,0 +1,86 @@
+import type { CCIPErrorCode } from './codes.ts'
+import { getDefaultRecovery } from './recovery.ts'
+
+/** Options for CCIPError constructor. */
+export interface CCIPErrorOptions {
+  /** Original error (ES2022 cause). */
+  cause?: Error
+  /** Structured context (IDs, addresses). */
+  context?: Record<string, unknown>
+  /** True if retry may succeed. */
+  isTransient?: boolean
+  /** Retry delay in ms. */
+  retryAfterMs?: number
+  /** Recovery suggestion. */
+  recovery?: string
+}
+
+/**
+ * Base error class for CCIP SDK.
+ *
+ * @example
+ * ```typescript
+ * if (CCIPError.isCCIPError(error) && error.isTransient) {
+ *   await sleep(error.retryAfterMs ?? 5000)
+ * }
+ * ```
+ */
+export class CCIPError extends Error {
+  /** Brand for cross-module identification (dual package hazard). */
+  readonly _isCCIPError = true as const
+  /** Machine-readable error code. */
+  readonly code: CCIPErrorCode
+  /** Structured context (IDs, addresses). */
+  readonly context: Record<string, unknown>
+  /** True if retry may succeed. */
+  readonly isTransient: boolean
+  /** Retry delay in ms. */
+  readonly retryAfterMs?: number
+  /** Recovery suggestion. */
+  readonly recovery?: string
+
+  override readonly name: string = 'CCIPError'
+
+  /** Creates CCIPError with code, message, and options. */
+  constructor(code: CCIPErrorCode, message: string, options?: CCIPErrorOptions) {
+    super(message, { cause: options?.cause })
+    Object.setPrototypeOf(this, new.target.prototype)
+
+    this.code = code
+    this.context = options?.context ?? {}
+    this.isTransient = options?.isTransient ?? false
+    this.retryAfterMs = options?.retryAfterMs
+    this.recovery = options?.recovery ?? getDefaultRecovery(code)
+
+    Error.captureStackTrace?.(this, this.constructor)
+  }
+
+  /** Type guard. Prefer over instanceof (handles dual package hazard). */
+  static isCCIPError(error: unknown): error is CCIPError {
+    return error instanceof CCIPError || !!(error as { _isCCIPError?: boolean })?._isCCIPError
+  }
+
+  /** Wrap unknown catch value in CCIPError. */
+  static from(error: unknown, code?: CCIPErrorCode): CCIPError {
+    if (error instanceof CCIPError) return error
+    if (error instanceof Error) {
+      return new CCIPError(code ?? 'UNKNOWN', error.message, { cause: error })
+    }
+    return new CCIPError(code ?? 'UNKNOWN', String(error))
+  }
+
+  /** Serialize for logging (JSON.stringify loses non-enumerable props). */
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      context: this.context,
+      isTransient: this.isTransient,
+      retryAfterMs: this.retryAfterMs,
+      recovery: this.recovery,
+      stack: this.stack,
+      cause: this.cause instanceof Error ? this.cause.message : this.cause,
+    }
+  }
+}