@chainlink/ccip-sdk 0.91.1 → 0.92.0

package/src/solana/logs.ts

@@ -0,0 +1,155 @@
+import { type Connection, PublicKey } from '@solana/web3.js'
+
+import type { LogFilter } from '../chain.ts'
+import type { SolanaTransaction } from './index.ts'
+import {
+  CCIPLogsAddressRequiredError,
+  CCIPLogsWatchRequiresFinalityError,
+  CCIPLogsWatchRequiresStartError,
+} from '../errors/index.ts'
+import { sleep } from '../utils.ts'
+
+const DEFAULT_POLL_INTERVAL = 5e3
+
+async function* fetchSigsForward(
+  opts: LogFilter & { pollInterval?: number },
+  ctx: { connection: Connection },
+) {
+  const { connection } = ctx
+  const limit = Math.min(opts?.page || 1000, 1000)
+  const commitment = opts.endBlock === 'finalized' ? 'finalized' : 'confirmed'
+
+  // forward collect all matching sigs in array
+  const allSigs = [] as Awaited<ReturnType<typeof connection.getSignaturesForAddress>>
+  let batch: typeof allSigs, until: string
+  do {
+    batch = await connection.getSignaturesForAddress(
+      new PublicKey(opts.address!),
+      { limit, before: allSigs[allSigs.length - 1]?.signature ?? opts.endBefore },
+      commitment,
+    )
+    until ??= batch[0]?.signature
+
+    while (
+      batch.length > 0 &&
+      (batch[batch.length - 1].slot < (opts.startBlock || 0) ||
+        (batch[batch.length - 1].blockTime || -1) < (opts.startTime || 0))
+    ) {
+      batch.length-- // truncate tail of txs which are older than requested start
+    }
+
+    allSigs.push(...batch) // concat in descending order
+  } while (batch.length >= limit)
+
+  allSigs.reverse() // forward
+
+  const notAfter =
+    typeof opts.endBlock !== 'number'
+      ? undefined
+      : opts.endBlock < 0
+        ? (await connection.getSlot('confirmed')) + opts.endBlock
+        : opts.endBlock
+  while (notAfter && allSigs.length > 0 && allSigs[allSigs.length - 1].slot > notAfter) {
+    allSigs.length-- // truncate head (after reverse) of txs newer than requested end
+  }
+  yield* allSigs // all past logs
+
+  if (allSigs.length) until = allSigs[allSigs.length - 1].signature
+  let lastReq = performance.now()
+  // if not watch mode, returns
+  while (opts.watch) {
+    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
+
+    lastReq = performance.now()
+    batch = await connection.getSignaturesForAddress(
+      new PublicKey(opts.address!),
+      { limit, until },
+      commitment,
+    )
+
+    batch.reverse() // forward
+
+    const notAfter =
+      batch.length === 0 || typeof opts.endBlock !== 'number'
+        ? undefined
+        : opts.endBlock < 0
+          ? (await connection.getSlot('confirmed')) + opts.endBlock
+          : opts.endBlock
+
+    for (const sig of batch) {
+      if (notAfter && sig.slot > notAfter) break
+      until = sig.signature
+      yield sig
+    }
+  }
+}
+
+async function* fetchSigsBackwards(
+  opts: LogFilter & { pollInterval?: number },
+  ctx: { connection: Connection },
+) {
+  const { connection } = ctx
+  const limit = Math.min(opts?.page || 1000, 1000)
+  const commitment = opts.endBlock === 'finalized' ? 'finalized' : 'confirmed'
+
+  if (typeof opts.endBlock === 'number' && opts.endBlock < 0)
+    opts.endBlock = (await connection.getSlot('confirmed')) + opts.endBlock
+
+  let batch: Awaited<ReturnType<typeof connection.getSignaturesForAddress>> | undefined
+  do {
+    batch = await connection.getSignaturesForAddress(
+      new PublicKey(opts.address!),
+      {
+        limit,
+        before: batch?.length
+          ? batch[batch.length - 1].signature
+          : opts.endBefore
+            ? opts.endBefore
+            : undefined,
+      },
+      commitment,
+    )
+    for (const sig of batch) {
+      if (typeof opts.endBlock === 'number' && sig.slot > opts.endBlock) continue
+      yield sig
+    }
+  } while (batch.length >= limit)
+}
+
+/**
+ * Internal method to get transactions for an address with pagination.
+ * @param opts - Log filter options.
+ * @returns Async generator of Solana transactions.
+ */
+export async function* getTransactionsForAddress(
+  opts: Omit<LogFilter, 'topics'> & { pollInterval?: number },
+  ctx: {
+    connection: Connection
+    getTransaction: (signature: string) => Promise<SolanaTransaction>
+  },
+): AsyncGenerator<SolanaTransaction> {
+  if (!opts.address) throw new CCIPLogsAddressRequiredError()
+
+  opts.endBlock ||= 'latest'
+
+  let allSignatures
+  if (opts.startBlock != null || opts.startTime != null) {
+    if (opts.watch && ((typeof opts.endBlock === 'number' && opts.endBlock > 0) || opts.endBefore))
+      throw new CCIPLogsWatchRequiresFinalityError(opts.endBlock)
+
+    allSignatures = fetchSigsForward(opts, ctx)
+  } else {
+    if (opts.watch) throw new CCIPLogsWatchRequiresStartError()
+
+    allSignatures = fetchSigsBackwards(opts, ctx) // generate backwards until depleting getSignaturesForAddress
+  }
+
+  // Process signatures
+  for await (const signatureInfo of allSignatures) {
+    yield await ctx.getTransaction(signatureInfo.signature)
+  }
+}

package/src/solana/offchain.ts

@@ -2,13 +2,18 @@ import { type BN, BorshCoder } from '@coral-xyz/anchor'
 import type { PublicKey } from '@solana/web3.js'
 import { hexlify } from 'ethers'
 
+import {
+  CCIPCctpDecodeError,
+  CCIPCctpMultipleEventsError,
+  CCIPDataFormatUnsupportedError,
+} from '../errors/index.ts'
 import { getUsdcAttestation } from '../offchain.ts'
 import type { CCIPMessage, CCIPRequest, OffchainTokenData, WithLogger } from '../types.ts'
-import { networkInfo, util } from '../utils.ts'
+import { bytesToBuffer, networkInfo, util } from '../utils.ts'
 import { IDL as BASE_TOKEN_POOL } from './idl/1.6.0/BASE_TOKEN_POOL.ts'
 import { IDL as CCTP_TOKEN_POOL } from './idl/1.6.0/CCIP_CCTP_TOKEN_POOL.ts'
 import type { SolanaLog, SolanaTransaction } from './index.ts'
-import { bytesToBuffer, hexDiscriminator } from './utils.ts'
+import { hexDiscriminator } from './utils.ts'
 
 interface CcipCctpMessageSentEvent {
   originalSender: PublicKey
@@ -53,7 +58,7 @@ export async function fetchSolanaOffchainTokenData(
   }
 
   if (request.message.tokenAmounts.length > 1) {
-    throw new Error(
+    throw new CCIPDataFormatUnsupportedError(
       `Expected at most 1 token transfer, found ${request.message.tokenAmounts?.length}`,
     )
   }
@@ -75,7 +80,7 @@ export async function fetchSolanaOffchainTokenData(
     if (requestInvokeIdx >= l.index || l.index >= log.index) continue
     if (l.topics[0] !== hexDiscriminator('CcipCctpMessageSentEvent')) continue
     const decoded = cctpTokenPoolCoder.events.decode(l.data)
-    if (!decoded) throw new Error(`Failed to decode CCTP event: ${util.inspect(l)}`)
+    if (!decoded) throw new CCIPCctpDecodeError(util.inspect(l))
     cctpEvents.push(decoded.data as unknown as CcipCctpMessageSentEvent)
   }
   const offchainTokenData: OffchainTokenData[] = request.message.tokenAmounts.map(() => undefined)
@@ -88,9 +93,7 @@ export async function fetchSolanaOffchainTokenData(
 
   // Currently, we only support ONE token per transfer
   if (cctpEvents.length > 1) {
-    throw new Error(
-      `Expected only 1 CcipCctpMessageSentEvent, found ${cctpEvents.length} in transaction ${txSignature}.`,
-    )
+    throw new CCIPCctpMultipleEventsError(cctpEvents.length, txSignature)
   }
 
   // NOTE: assuming USDC token is the first (and only) token in the CCIP message, we will process the CCTP event.

package/src/solana/patchBorsh.ts

@@ -4,6 +4,7 @@ import { BorshInstructionCoder } from '@coral-xyz/anchor'
 import { BorshTypesCoder } from '@coral-xyz/anchor/dist/cjs/coder/borsh/types.js'
 import { sha256, toUtf8Bytes } from 'ethers'
 
+import { CCIPBorshMethodUnknownError, CCIPBorshTypeUnknownError } from '../errors/index.ts'
 import { snakeToCamel } from '../utils.ts'
 import { camelToSnakeCase } from './utils.ts'
 
@@ -30,7 +31,7 @@ export function patchBorsh() {
         name,
       )
       if (!layout) {
-        throw new Error(`Unknown type: ${name}`)
+        throw new CCIPBorshTypeUnknownError(name)
       }
       let buffer = Buffer.alloc(512)
       let len
@@ -61,7 +62,7 @@ export function patchBorsh() {
         methodName,
       )
       if (!layout) {
-        throw new Error(`Unknown method: ${methodName}`)
+        throw new CCIPBorshMethodUnknownError(methodName)
       }
       let buffer = Buffer.alloc(512)
       let len

package/src/solana/send.ts

@@ -18,11 +18,18 @@ import BN from 'bn.js'
 import { zeroPadValue } from 'ethers'
 
 import { SolanaChain } from './index.ts'
+import {
+  CCIPSolanaFeeResultInvalidError,
+  CCIPSolanaLookupTableNotFoundError,
+  CCIPSolanaRouterConfigNotFoundError,
+  CCIPTokenAmountInvalidError,
+  CCIPTokenMintNotFoundError,
+} from '../errors/index.ts'
 import { type AnyMessage, type WithLogger, ChainFamily } from '../types.ts'
-import { toLeArray, util } from '../utils.ts'
+import { bytesToBuffer, toLeArray, util } from '../utils.ts'
 import { IDL as CCIP_ROUTER_IDL } from './idl/1.6.0/CCIP_ROUTER.ts'
 import type { UnsignedSolanaTx } from './types.ts'
-import { bytesToBuffer, simulationProvider } from './utils.ts'
+import { simulationProvider } from './utils.ts'
 
 function anyToSvmMessage(message: AnyMessage): IdlTypes<typeof CCIP_ROUTER_IDL>['SVM2AnyMessage'] {
   const feeTokenPubkey = message.feeToken ? new PublicKey(message.feeToken) : PublicKey.default
@@ -32,7 +39,7 @@ function anyToSvmMessage(message: AnyMessage): IdlTypes<typeof CCIP_ROUTER_IDL>[
     data: bytesToBuffer(message.data || '0x'),
     tokenAmounts: (message.tokenAmounts || []).map((ta) => {
       if (!ta.token || ta.amount < 0n) {
-        throw new Error('Invalid token amount: token address and positive amount required')
+        throw new CCIPTokenAmountInvalidError()
       }
       return {
         token: new PublicKey(ta.token),
@@ -66,7 +73,7 @@ export async function getFee(
   // Get router config to find feeQuoter
   const [configPda] = PublicKey.findProgramAddressSync([Buffer.from('config')], program.programId)
   const configAccount = await connection.getAccountInfo(configPda)
-  if (!configAccount) throw new Error(`Router config not found at ${configPda.toBase58()}`)
+  if (!configAccount) throw new CCIPSolanaRouterConfigNotFoundError(configPda.toBase58())
 
   const { feeQuoter, linkTokenMint }: { feeQuoter: PublicKey; linkTokenMint: PublicKey } =
     program.coder.accounts.decode('config', configAccount.data)
@@ -147,7 +154,7 @@ export async function getFee(
     .view()) as IdlTypes<typeof CCIP_ROUTER_IDL>['GetFeeResult']
 
   if (!result?.amount) {
-    throw new Error(`Invalid fee result from router: ${util.inspect(result)}`)
+    throw new CCIPSolanaFeeResultInvalidError(util.inspect(result))
   }
 
   return BigInt(result.amount.toString())
@@ -224,7 +231,7 @@ async function deriveAccountsCcipSend({
         const lookupTableAccountInfo = await connection.getAddressLookupTable(table)
 
         if (!lookupTableAccountInfo.value) {
-          throw new Error(`Lookup table account not found: ${table.toBase58()}`)
+          throw new CCIPSolanaLookupTableNotFoundError(table.toBase58())
         }
 
         return lookupTableAccountInfo.value
@@ -332,7 +339,7 @@ async function approveRouterSpender(
 ): Promise<TransactionInstruction | undefined> {
   // Get the current account info to check existing delegation (or create if needed)
   const mintInfo = await connection.getAccountInfo(token)
-  if (!mintInfo) throw new Error(`Mint ${token.toBase58()} not found`)
+  if (!mintInfo) throw new CCIPTokenMintNotFoundError(token.toBase58())
   const associatedTokenAccount = getAssociatedTokenAddressSync(
     token,
     owner,

package/src/solana/utils.ts

@@ -1,6 +1,4 @@
-import { Buffer } from 'buffer'
-
-import { eventDiscriminator } from '@coral-xyz/anchor'
+import { type IdlTypes, eventDiscriminator } from '@coral-xyz/anchor'
 import {
   type AddressLookupTableAccount,
   type Connection,
@@ -14,11 +12,17 @@ import {
   TransactionMessage,
   VersionedTransaction,
 } from '@solana/web3.js'
-import { type BytesLike, dataLength, dataSlice, hexlify } from 'ethers'
+import { dataLength, dataSlice, hexlify } from 'ethers'
 
+import {
+  CCIPSolanaComputeUnitsExceededError,
+  CCIPTransactionNotFinalizedError,
+} from '../errors/index.ts'
 import type { Log_, WithLogger } from '../types.ts'
 import { getDataBytes, sleep } from '../utils.ts'
+import type { IDL as BASE_TOKEN_POOL_IDL } from './idl/1.6.0/BASE_TOKEN_POOL.ts'
 import type { UnsignedSolanaTx, Wallet } from './types.ts'
+import type { RateLimiterState } from '../chain.ts'
 
 /**
  * Generates a hex-encoded discriminator for a Solana event.
@@ -29,15 +33,6 @@ export function hexDiscriminator(eventName: string): string {
   return hexlify(eventDiscriminator(eventName))
 }
 
-/**
- * Converts bytes to a Node.js Buffer.
- * @param bytes - Bytes to convert.
- * @returns Node.js Buffer.
- */
-export function bytesToBuffer(bytes: BytesLike): Buffer {
-  return Buffer.from(getDataBytes(bytes).buffer)
-}
-
 /**
  * Waits for a Solana transaction to reach finalized status.
  * @param connection - Solana connection instance.
@@ -61,7 +56,7 @@ export async function waitForFinalization(
     await sleep(intervalMs)
   }
 
-  throw new Error(`Transaction ${signature} not finalized after timeout`)
+  throw new CCIPTransactionNotFinalizedError(signature)
 }
 
 /**
@@ -361,9 +356,7 @@ export async function simulateAndSendTxs(
         } else if (!includesMain || computeUnits == null || simulated <= computeUnits) {
           computeUnitLimit = Math.ceil(simulated * 1.1)
         } else {
-          throw new Error(
-            `Main simulation exceeds specified computeUnits limit. simulated=${simulated}, limit=${computeUnits}`,
-          )
+          throw new CCIPSolanaComputeUnitsExceededError(simulated, computeUnits)
         }
         break
       } catch (err) {
@@ -394,3 +387,24 @@ export async function simulateAndSendTxs(
   }
   return mainHash!
 }
+
+/**
+ * Convert TokenPool's rate limit to RateLimiterState object
+ */
+export function convertRateLimiter(
+  input: IdlTypes<typeof BASE_TOKEN_POOL_IDL>['BaseChain']['inboundRateLimit'],
+): RateLimiterState {
+  if (!input.cfg.enabled) return null
+  const tokens = BigInt(input.tokens.toString())
+  const out: RateLimiterState = {
+    capacity: BigInt(input.cfg.capacity.toString()),
+    rate: BigInt(input.cfg.rate.toString()),
+    get tokens() {
+      const cur =
+        tokens + this.rate * BigInt(Math.floor(Date.now() / 1000) - input.lastUpdated.toNumber())
+      if (cur < this.capacity) return cur
+      else return this.capacity
+    },
+  }
+  return out
+}

package/src/sui/discovery.ts

@@ -0,0 +1,163 @@
+import type { SuiClient } from '@mysten/sui/client'
+import { Transaction } from '@mysten/sui/transactions'
+import { normalizeSuiAddress } from '@mysten/sui/utils'
+import { hexlify } from 'ethers'
+
+import { CCIPError } from '../errors/CCIPError.ts'
+import { CCIPErrorCode } from '../errors/codes.ts'
+import { bytesToBuffer } from '../utils.ts'
+
+/**
+ * Discovers the CCIP package ID associated with a given Sui onramp package.
+ *
+ * @param client - sui client
+ * @param onramp - sui onramp package id
+ * @returns ccip package id
+ */
+export const discoverCCIP = async (client: SuiClient, onramp: string): Promise<string> => {
+  const tx = new Transaction()
+  tx.moveCall({
+    target: `${onramp}::onramp::get_ccip_package_id`,
+  })
+
+  const inspectResult = await client.devInspectTransactionBlock({
+    sender: normalizeSuiAddress('0x0'),
+    transactionBlock: tx,
+  })
+  const returnValues = inspectResult.results?.[0]?.returnValues
+  if (!returnValues || returnValues.length === 0) {
+    throw new CCIPError(CCIPErrorCode.UNKNOWN, 'No return values from dev inspect')
+  }
+  const [valueBytes] = returnValues[0]
+  if (!valueBytes) {
+    throw new CCIPError(
+      CCIPErrorCode.UNKNOWN,
+      'Unable to decode CCIP package id from return values',
+    )
+  }
+
+  return normalizeSuiAddress(hexlify(bytesToBuffer(valueBytes)))
+}
+
+/**
+ * Gets the Sui offramp package ID associated with a given CCIP package ID.
+ *
+ * @param client - Sui client
+ * @param ccip - Sui CCIP Package Id
+ * @returns Sui offramp package id
+ */
+export const discoverOfframp = async (client: SuiClient, ccip: string) => {
+  // Get CCIP publish tx info
+  // Get the owner cap created in that tx.
+  // Get owner of the ownercap object.
+  // Get objects owned by that owner.
+  // Trough each of the objects owned by that owner, get the original transaction that created them.
+  // Take any of the objects created by that transaction, check its info to find the OffRamp package.
+  const ccipObject = await client.getObject({
+    id: ccip,
+    options: {
+      showPreviousTransaction: true,
+    },
+  })
+
+  // Get the tx that created the ownercap object.
+  const ccipCreationTxDigest = ccipObject.data?.previousTransaction
+  if (!ccipCreationTxDigest) {
+    throw new CCIPError(
+      CCIPErrorCode.UNKNOWN,
+      'Could not find previous transaction for CCIP object',
+    )
+  }
+
+  const ccipCreationTx = await client.getTransactionBlock({
+    digest: ccipCreationTxDigest,
+    options: {
+      showEffects: true,
+    },
+  })
+
+  const ccipCreatedObjects = ccipCreationTx.effects?.created?.map((obj) => obj.reference.objectId)
+  if (!ccipCreatedObjects || ccipCreatedObjects.length === 0) {
+    throw new CCIPError(CCIPErrorCode.UNKNOWN, 'No created objects found in creation transaction')
+  }
+
+  const ccipObjectsData = await Promise.all(
+    ccipCreatedObjects.map((objId) =>
+      client.getObject({
+        id: objId,
+        options: {
+          showType: true,
+          showContent: true,
+          showOwner: true,
+        },
+      }),
+    ),
+  )
+
+  const ownerCapObject = ccipObjectsData.find((objData) =>
+    objData.data?.type?.includes('::ownable::OwnerCap'),
+  )
+
+  if (!ownerCapObject) {
+    throw new CCIPError(CCIPErrorCode.UNKNOWN, 'OwnerCap object not found among created objects')
+  }
+
+  const ownerCapOwner = ownerCapObject.data?.owner
+  if (!ownerCapOwner) {
+    throw new CCIPError(CCIPErrorCode.UNKNOWN, 'Could not find owner of the OwnerCap object')
+  }
+
+  if (typeof ownerCapOwner === 'string' || !('AddressOwner' in ownerCapOwner)) {
+    throw new CCIPError(CCIPErrorCode.UNKNOWN, 'OwnerCap object does not have an AddressOwner')
+  }
+
+  const ownerCapOwnerObjects = await client.getOwnedObjects({
+    owner: ownerCapOwner['AddressOwner'],
+  })
+
+  const fullObjectsInfo = await Promise.all(
+    ownerCapOwnerObjects.data.map((obj) =>
+      client.getObject({
+        id: obj.data?.objectId || '',
+        options: {
+          showType: true,
+        },
+      }),
+    ),
+  )
+
+  const ownerCapPackageIds = fullObjectsInfo
+    .filter((objData) => objData.data?.type?.includes('::ownable::OwnerCap'))
+    .map((obj) => obj.data?.type?.split('::')[0])
+
+  const packagesInfo = await Promise.all(
+    ownerCapPackageIds.map((pkgId) =>
+      client.getNormalizedMoveModulesByPackage({
+        package: pkgId || '',
+      }),
+    ),
+  )
+
+  const offrampPkgs = packagesInfo
+    .filter((pkg) => {
+      return Object.values(pkg).some((module) => module.name === 'offramp')
+    })
+    .flatMap((pkg) => Object.values(pkg))
+    .filter((module) => module.name === 'offramp')
+
+  if (offrampPkgs.length === 0) {
+    throw new CCIPError(
+      CCIPErrorCode.UNKNOWN,
+      'Could not find OffRamp package among OwnerCap packages',
+    )
+  }
+
+  if (offrampPkgs.length > 1) {
+    throw new CCIPError(
+      CCIPErrorCode.UNKNOWN,
+      'Multiple OffRamp packages found; unable to uniquely identify OffRamp package',
+    )
+  }
+
+  return normalizeSuiAddress(offrampPkgs[0].address)
+}