@chainlink/ccip-sdk 0.94.0 → 0.96.0

package/src/evm/extra-args.ts

@@ -0,0 +1,377 @@
+import {
+  type BytesLike,
+  Result,
+  concat,
+  dataSlice,
+  encodeBase58,
+  getAddress,
+  hexlify,
+  toBeHex,
+  toBigInt,
+  toNumber,
+  zeroPadValue,
+} from 'ethers'
+
+import {
+  type EVMExtraArgsV1,
+  type EVMExtraArgsV2,
+  type ExtraArgs,
+  type GenericExtraArgsV3,
+  type SVMExtraArgsV1,
+  type SuiExtraArgsV1,
+  EVMExtraArgsV1Tag,
+  EVMExtraArgsV2Tag,
+  GenericExtraArgsV3Tag,
+  SVMExtraArgsV1Tag,
+  SuiExtraArgsV1Tag,
+} from '../extra-args.ts'
+import { getAddressBytes, getDataBytes } from '../utils.ts'
+import { DEFAULT_GAS_LIMIT, defaultAbiCoder } from './const.ts'
+
+// ABI type strings for extra args encoding
+const EVMExtraArgsV1ABI = 'tuple(uint256 gasLimit)'
+const EVMExtraArgsV2ABI = 'tuple(uint256 gasLimit, bool allowOutOfOrderExecution)'
+const SVMExtraArgsV1ABI =
+  'tuple(uint32 computeUnits, uint64 accountIsWritableBitmap, bool allowOutOfOrderExecution, bytes32 tokenReceiver, bytes32[] accounts)'
+const SuiExtraArgsV1ABI =
+  'tuple(uint256 gasLimit, bool allowOutOfOrderExecution, bytes32 tokenReceiver, bytes32[] receiverObjectIds)'
+
+/**
+ * Converts an ethers Result to a plain object.
+ * @internal
+ */
+function resultToObject<T>(o: T): T {
+  if (o instanceof Promise) return o.then(resultToObject) as T
+  if (!(o instanceof Result)) return o
+  if (o.length === 0) return o.toArray() as T
+  try {
+    const obj = o.toObject()
+    if (!Object.keys(obj).every((k) => /^_+\d*$/.test(k)))
+      return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, resultToObject(v)])) as T
+  } catch (_) {
+    // fallthrough
+  }
+  return o.toArray().map(resultToObject) as T
+}
+
+/**
+ * Encodes GenericExtraArgsV3 using tightly packed binary format.
+ *
+ * Binary format:
+ * - tag (4 bytes): 0x302326cb
+ * - gasLimit (4 bytes): uint32 big-endian
+ * - blockConfirmations (2 bytes): uint16 big-endian
+ * - ccvsLength (1 byte): uint8
+ * - For each CCV:
+ *   - ccvAddressLength (1 byte): 0 or 20
+ *   - ccvAddress (0 or 20 bytes)
+ *   - ccvArgsLength (2 bytes): uint16 big-endian
+ *   - ccvArgs (variable)
+ * - executorLength (1 byte): 0 or 20
+ * - executor (0 or 20 bytes)
+ * - executorArgsLength (2 bytes): uint16 big-endian
+ * - executorArgs (variable)
+ * - tokenReceiverLength (1 byte): uint8
+ * - tokenReceiver (variable)
+ * - tokenArgsLength (2 bytes): uint16 big-endian
+ * - tokenArgs (variable)
+ */
+function encodeExtraArgsV3(args: GenericExtraArgsV3): string {
+  const parts: Uint8Array[] = []
+
+  // Tag (4 bytes)
+  parts.push(getDataBytes(GenericExtraArgsV3Tag))
+
+  // gasLimit (4 bytes, uint32 big-endian)
+  parts.push(getDataBytes(toBeHex(args.gasLimit, 4)))
+
+  // blockConfirmations (2 bytes, uint16 big-endian)
+  parts.push(getDataBytes(toBeHex(args.blockConfirmations, 2)))
+
+  // ccvsLength (1 byte)
+  parts.push(new Uint8Array([args.ccvs.length]))
+
+  // For each CCV
+  for (let i = 0; i < args.ccvs.length; i++) {
+    const ccvAddress = args.ccvs[i]!
+    const ccvArgsBytes = getDataBytes(args.ccvArgs[i] ?? '0x')
+
+    if (ccvAddress && ccvAddress !== '' && ccvAddress !== '0x') {
+      // ccvAddressLength = 20
+      parts.push(new Uint8Array([20]))
+      // ccvAddress (20 bytes)
+      parts.push(getDataBytes(ccvAddress))
+    } else {
+      // ccvAddressLength = 0
+      parts.push(new Uint8Array([0]))
+    }
+
+    // ccvArgsLength (2 bytes, uint16 big-endian)
+    parts.push(getDataBytes(toBeHex(ccvArgsBytes.length, 2)))
+
+    // ccvArgs (variable)
+    if (ccvArgsBytes.length > 0) {
+      parts.push(ccvArgsBytes)
+    }
+  }
+
+  // executorLength (1 byte)
+  if (args.executor && args.executor !== '' && args.executor !== '0x') {
+    parts.push(new Uint8Array([20]))
+    parts.push(getDataBytes(args.executor))
+  } else {
+    parts.push(new Uint8Array([0]))
+  }
+
+  // Convert BytesLike fields to Uint8Array
+  const executorArgsBytes = getDataBytes(args.executorArgs)
+  const tokenReceiverBytes = getDataBytes(args.tokenReceiver)
+  const tokenArgsBytes = getDataBytes(args.tokenArgs)
+
+  // executorArgsLength (2 bytes, uint16 big-endian)
+  parts.push(getDataBytes(toBeHex(executorArgsBytes.length, 2)))
+
+  // executorArgs (variable)
+  if (executorArgsBytes.length > 0) {
+    parts.push(executorArgsBytes)
+  }
+
+  // tokenReceiverLength (1 byte)
+  parts.push(new Uint8Array([tokenReceiverBytes.length]))
+
+  // tokenReceiver (variable)
+  if (tokenReceiverBytes.length > 0) {
+    parts.push(tokenReceiverBytes)
+  }
+
+  // tokenArgsLength (2 bytes, uint16 big-endian)
+  parts.push(getDataBytes(toBeHex(tokenArgsBytes.length, 2)))
+
+  // tokenArgs (variable)
+  if (tokenArgsBytes.length > 0) {
+    parts.push(tokenArgsBytes)
+  }
+
+  return hexlify(concat(parts))
+}
+
+/**
+ * Decodes GenericExtraArgsV3 from tightly packed binary format.
+ * @param data - Bytes to decode (without the tag prefix).
+ * @returns Decoded GenericExtraArgsV3 or undefined if parsing fails.
+ */
+function decodeExtraArgsV3(data: Uint8Array): GenericExtraArgsV3 | undefined {
+  let offset = 0
+
+  // gasLimit (4 bytes, uint32 big-endian)
+  if (offset + 4 > data.length) return undefined
+  const gasLimit = toBigInt(data.subarray(offset, offset + 4))
+  offset += 4
+
+  // blockConfirmations (2 bytes, uint16 big-endian)
+  if (offset + 2 > data.length) return undefined
+  const blockConfirmations = toNumber(data.subarray(offset, offset + 2))
+  offset += 2
+
+  // ccvsLength (1 byte)
+  if (offset + 1 > data.length) return undefined
+  const ccvsLength = data[offset]!
+  offset += 1
+
+  const ccvs: string[] = []
+  const ccvArgs: string[] = []
+
+  // For each CCV
+  for (let i = 0; i < ccvsLength; i++) {
+    // ccvAddressLength (1 byte)
+    if (offset + 1 > data.length) return undefined
+    const ccvAddrLen = data[offset]!
+    offset += 1
+
+    // ccvAddress (0 or 20 bytes)
+    if (ccvAddrLen === 20) {
+      if (offset + 20 > data.length) return undefined
+      ccvs.push(getAddress(hexlify(data.slice(offset, offset + 20))))
+      offset += 20
+    } else if (ccvAddrLen === 0) {
+      ccvs.push('')
+    } else {
+      return undefined // Invalid address length
+    }
+
+    // ccvArgsLength (2 bytes, uint16 big-endian)
+    if (offset + 2 > data.length) return undefined
+    const ccvArgsLen = toNumber(data.subarray(offset, offset + 2))
+    offset += 2
+
+    // ccvArgs (variable)
+    if (offset + ccvArgsLen > data.length) return undefined
+    ccvArgs.push(hexlify(data.slice(offset, offset + ccvArgsLen)))
+    offset += ccvArgsLen
+  }
+
+  // executorLength (1 byte)
+  if (offset + 1 > data.length) return undefined
+  const executorLen = data[offset]!
+  offset += 1
+
+  // executor (0 or 20 bytes)
+  let executor = ''
+  if (executorLen === 20) {
+    if (offset + 20 > data.length) return undefined
+    executor = getAddress(hexlify(data.slice(offset, offset + 20)))
+    offset += 20
+  } else if (executorLen !== 0) {
+    return undefined // Invalid executor length
+  }
+
+  // executorArgsLength (2 bytes, uint16 big-endian)
+  if (offset + 2 > data.length) return undefined
+  const executorArgsLen = toNumber(data.subarray(offset, offset + 2))
+  offset += 2
+
+  // executorArgs (variable)
+  if (offset + executorArgsLen > data.length) return undefined
+  const executorArgs = hexlify(data.slice(offset, offset + executorArgsLen))
+  offset += executorArgsLen
+
+  // tokenReceiverLength (1 byte)
+  if (offset + 1 > data.length) return undefined
+  const tokenReceiverLen = data[offset]!
+  offset += 1
+
+  // tokenReceiver (variable)
+  if (offset + tokenReceiverLen > data.length) return undefined
+  const tokenReceiverBytes = data.slice(offset, offset + tokenReceiverLen)
+  offset += tokenReceiverLen
+
+  // Convert tokenReceiver bytes to string
+  let tokenReceiver: string
+  if (tokenReceiverLen === 0) {
+    tokenReceiver = ''
+  } else if (tokenReceiverLen === 20) {
+    // 20 bytes = EVM address, return checksummed
+    tokenReceiver = getAddress(hexlify(tokenReceiverBytes))
+  } else {
+    // Other lengths: return as hex string
+    tokenReceiver = hexlify(tokenReceiverBytes)
+  }
+
+  // tokenArgsLength (2 bytes, uint16 big-endian)
+  if (offset + 2 > data.length) return undefined
+  const tokenArgsLen = toNumber(data.subarray(offset, offset + 2))
+  offset += 2
+
+  // tokenArgs (variable)
+  if (offset + tokenArgsLen > data.length) return undefined
+  const tokenArgs = hexlify(data.slice(offset, offset + tokenArgsLen))
+  offset += tokenArgsLen
+
+  return {
+    gasLimit,
+    blockConfirmations,
+    ccvs,
+    ccvArgs,
+    executor,
+    executorArgs,
+    tokenReceiver,
+    tokenArgs,
+  }
+}
+
+/**
+ * Decodes extra arguments from a CCIP message.
+ * @param extraArgs - Encoded extra arguments bytes.
+ * @returns Decoded extra arguments with tag, or undefined if unknown format.
+ */
+export function decodeExtraArgs(
+  extraArgs: BytesLike,
+):
+  | (EVMExtraArgsV1 & { _tag: 'EVMExtraArgsV1' })
+  | (EVMExtraArgsV2 & { _tag: 'EVMExtraArgsV2' })
+  | (GenericExtraArgsV3 & { _tag: 'GenericExtraArgsV3' })
+  | (SVMExtraArgsV1 & { _tag: 'SVMExtraArgsV1' })
+  | (SuiExtraArgsV1 & { _tag: 'SuiExtraArgsV1' })
+  | undefined {
+  const data = getDataBytes(extraArgs),
+    tag = dataSlice(data, 0, 4)
+  switch (tag) {
+    case EVMExtraArgsV1Tag: {
+      const args = defaultAbiCoder.decode([EVMExtraArgsV1ABI], dataSlice(data, 4))
+      return { ...(resultToObject(args[0]) as EVMExtraArgsV1), _tag: 'EVMExtraArgsV1' }
+    }
+    case EVMExtraArgsV2Tag: {
+      const args = defaultAbiCoder.decode([EVMExtraArgsV2ABI], dataSlice(data, 4))
+      return { ...(resultToObject(args[0]) as EVMExtraArgsV2), _tag: 'EVMExtraArgsV2' }
+    }
+    case GenericExtraArgsV3Tag: {
+      const parsed = decodeExtraArgsV3(data.slice(4))
+      if (!parsed) return undefined
+      return { ...parsed, _tag: 'GenericExtraArgsV3' }
+    }
+    case SVMExtraArgsV1Tag: {
+      const args = defaultAbiCoder.decode([SVMExtraArgsV1ABI], dataSlice(data, 4))
+      const parsed = resultToObject(args[0]) as SVMExtraArgsV1
+      parsed.tokenReceiver = encodeBase58(parsed.tokenReceiver)
+      parsed.accounts = parsed.accounts.map((a: string) => encodeBase58(a))
+      return { ...parsed, _tag: 'SVMExtraArgsV1' }
+    }
+    case SuiExtraArgsV1Tag: {
+      const args = defaultAbiCoder.decode([SuiExtraArgsV1ABI], dataSlice(data, 4))
+      const parsed = resultToObject(args[0]) as SuiExtraArgsV1
+      return {
+        ...parsed,
+        _tag: 'SuiExtraArgsV1',
+      }
+    }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Encodes extra arguments for a CCIP message.
+ * @param args - Extra arguments to encode.
+ * @returns Encoded extra arguments as hex string.
+ */
+export function encodeExtraArgs(args: ExtraArgs | undefined): string {
+  if (!args) return '0x'
+  if ('blockConfirmations' in args) {
+    // GenericExtraArgsV3 - tightly packed binary encoding
+    return encodeExtraArgsV3(args)
+  } else if ('computeUnits' in args) {
+    return concat([
+      SVMExtraArgsV1Tag,
+      defaultAbiCoder.encode(
+        [SVMExtraArgsV1ABI],
+        [
+          {
+            ...args,
+            tokenReceiver: getAddressBytes(args.tokenReceiver),
+            accounts: args.accounts.map((a) => getAddressBytes(a)),
+          },
+        ],
+      ),
+    ])
+  } else if ('receiverObjectIds' in args) {
+    return concat([
+      SuiExtraArgsV1Tag,
+      defaultAbiCoder.encode(
+        [SuiExtraArgsV1ABI],
+        [
+          {
+            ...args,
+            tokenReceiver: zeroPadValue(getAddressBytes(args.tokenReceiver), 32),
+            receiverObjectIds: args.receiverObjectIds.map((a) => getDataBytes(a)),
+          },
+        ],
+      ),
+    ])
+  } else if ('allowOutOfOrderExecution' in args) {
+    if ((args as Partial<typeof args>).gasLimit == null) args.gasLimit = DEFAULT_GAS_LIMIT
+    return concat([EVMExtraArgsV2Tag, defaultAbiCoder.encode([EVMExtraArgsV2ABI], [args])])
+  } else if ((args as Partial<typeof args>).gasLimit != null) {
+    return concat([EVMExtraArgsV1Tag, defaultAbiCoder.encode([EVMExtraArgsV1ABI], [args])])
+  }
+  return '0x'
+}

package/src/evm/gas.ts

@@ -0,0 +1,150 @@
+import {
+  type JsonRpcApiProvider,
+  Contract,
+  FunctionFragment,
+  concat,
+  getAddress,
+  getNumber,
+  hexlify,
+  randomBytes,
+  solidityPackedKeccak256,
+  toBeHex,
+  zeroPadValue,
+} from 'ethers'
+import type { TypedContract } from 'ethers-abitype'
+import { memoize } from 'micro-memoize'
+
+import type { Chain } from '../chain.ts'
+import TokenABI from './abi/BurnMintERC677Token.ts'
+import RouterABI from './abi/Router.ts'
+import { defaultAbiCoder, interfaces } from './const.ts'
+import { getAddressBytes, getDataBytes } from '../utils.ts'
+
+const ccipReceive = FunctionFragment.from({
+  type: 'function',
+  name: 'ccipReceive',
+  stateMutability: 'nonpayable',
+  inputs: RouterABI.find((v) => v.type === 'function' && v.name === 'routeMessage')!.inputs.slice(
+    0,
+    1,
+  ),
+  outputs: [],
+})
+type Any2EVMMessage = Parameters<TypedContract<typeof RouterABI>['routeMessage']>[0]
+
+/**
+ * Finds suitable token balance slot by simulating a fake transfer between 2 non-existent accounts,
+ * with state overrides for the holders' balance, which reverts if override slot is wrong
+ */
+const findBalancesSlot = memoize(
+  async function findBalancesSlot_(
+    token: string,
+    provider: JsonRpcApiProvider,
+    holder: string = getAddress(hexlify(randomBytes(20))),
+    recipient: string = getAddress(hexlify(randomBytes(20))),
+  ): Promise<number> {
+    const contract = new Contract(token, interfaces.Token, provider) as unknown as TypedContract<
+      typeof TokenABI
+    >
+    const fakeAmount = (await contract.totalSupply()) + 1n
+    const calldata = interfaces.Token.encodeFunctionData('transfer', [recipient, fakeAmount])
+
+    let firstErr
+    // try range(0..15), but start with most probable 0 (common ERC20) and 9 (USDC)
+    for (const slot of [0, 9, 1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 13, 14, 15]) {
+      try {
+        await provider.send('eth_estimateGas', [
+          { from: holder, to: token, data: calldata },
+          'latest',
+          {
+            [token]: {
+              stateDiff: {
+                [solidityPackedKeccak256(['uint256', 'uint256'], [holder, slot])]: toBeHex(
+                  fakeAmount,
+                  32,
+                ),
+              },
+            },
+          },
+        ])
+        return slot // if didn't reject
+      } catch (err) {
+        firstErr ??= err
+      }
+    }
+    throw firstErr as Error
+  },
+  { maxArgs: 1 },
+)
+
+type EstimateExecGasOpts = Pick<
+  Parameters<NonNullable<Chain['estimateReceiveExecution']>>[0],
+  'message' | 'receiver'
+> & {
+  /*  */
+  provider: JsonRpcApiProvider
+  router: string
+}
+
+/**
+ * Estimate gasLimit needed to execute a request on a receiver contract.
+ * @param opts - Options for estimation: provider, destRouter, receiver address and message
+ * @returns Estimated gasLimit
+ */
+export async function estimateExecGas({
+  provider,
+  router,
+  receiver,
+  message,
+}: EstimateExecGasOpts) {
+  // we need to override the state, increasing receiver's balance for each token, to simulate the
+  // state after tokens were transferred by the offRamp just before calling `ccipReceive`
+  const destAmounts: Record<string, bigint> = {}
+  const stateOverrides: Record<string, { stateDiff: Record<string, string> }> = {}
+  for (const { token, amount } of message.destTokenAmounts ?? []) {
+    if (!(token in destAmounts)) {
+      const tokenContract = new Contract(token, TokenABI, provider) as unknown as TypedContract<
+        typeof TokenABI
+      >
+      const currentBalance = await tokenContract.balanceOf(receiver)
+      destAmounts[token] = currentBalance
+    }
+    destAmounts[token]! += amount
+    const balancesSlot = await findBalancesSlot(token, provider, receiver, router)
+    stateOverrides[token] = {
+      stateDiff: {
+        [solidityPackedKeccak256(['uint256', 'uint256'], [receiver, balancesSlot])]: toBeHex(
+          destAmounts[token]!,
+          32,
+        ),
+      },
+    }
+  }
+
+  const receiverMsg: Any2EVMMessage = {
+    ...message,
+    destTokenAmounts: message.destTokenAmounts ?? [],
+    sender: zeroPadValue(getAddressBytes(message.sender ?? '0x'), 32),
+    data: hexlify(getDataBytes(message.data || '0x')),
+    sourceChainSelector: message.sourceChainSelector,
+  }
+  const calldata = concat([
+    ccipReceive.selector,
+    defaultAbiCoder.encode(ccipReceive.inputs, [receiverMsg]),
+  ])
+
+  return (
+    getNumber(
+      (await provider.send('eth_estimateGas', [
+        {
+          from: router,
+          to: receiver,
+          data: calldata,
+        },
+        'latest',
+        ...(Object.keys(stateOverrides).length ? [stateOverrides] : []),
+      ])) as string,
+    ) -
+    (21_000 - 700) // 21k is the base gas cost for a transaction, 700 is the gas cost of the call
+  )
+}