@chainlink/ccip-sdk 0.95.0 → 0.97.0

package/src/ton/send.ts

@@ -0,0 +1,222 @@
+import { type Cell, beginCell, toNano } from '@ton/core'
+import { type TonClient, Address } from '@ton/ton'
+import { zeroPadValue } from 'ethers'
+
+import type { UnsignedTONTx } from './types.ts'
+import { CCIPError, CCIPErrorCode } from '../errors/index.ts'
+import { EVMExtraArgsV2Tag } from '../extra-args.ts'
+import type { AnyMessage, WithLogger } from '../types.ts'
+import { bytesToBuffer, getDataBytes } from '../utils.ts'
+
+/** Opcode for Router ccipSend operation */
+export const CCIP_SEND_OPCODE = 0x31768d95
+
+/** Default gas buffer to add to fee for transaction execution */
+export const DEFAULT_GAS_BUFFER = toNano('0.5')
+
+/** Default gas limit for destination chain execution */
+export const DEFAULT_GAS_LIMIT = 200_000n
+
+/**
+ * WRAPPED_NATIVE address for TON - sentinel address representing native TON.
+ * Used as feeToken for native TON payments in FeeQuoter calls.
+ */
+export const WRAPPED_NATIVE = Address.parse(
+  '0:0000000000000000000000000000000000000000000000000000000000000001',
+)
+
+/**
+ * Encodes token amounts as a snaked cell.
+ * Empty cell for no tokens.
+ */
+function encodeTokenAmounts(
+  tokenAmounts: readonly { token: string; amount: bigint }[] | undefined,
+): Cell {
+  if (!tokenAmounts || tokenAmounts.length === 0) {
+    return beginCell().endCell()
+  }
+
+  const builder = beginCell()
+  for (const ta of tokenAmounts) {
+    builder.storeRef(
+      beginCell().storeAddress(Address.parse(ta.token)).storeUint(ta.amount, 256).endCell(),
+    )
+  }
+  return builder.endCell()
+}
+
+/**
+ * Encodes extraArgs as a Cell using the GenericExtraArgsV2 (EVMExtraArgsV2) format.
+ *
+ * Format per chainlink-ton TL-B:
+ * - tag: 32-bit opcode (0x181dcf10)
+ * - gasLimit: Maybe<uint256> (1 bit flag + 256 bits if present)
+ * - allowOutOfOrderExecution: 1 bit (must be true)
+ */
+function encodeExtraArgsCell(extraArgs: AnyMessage['extraArgs']): Cell {
+  const allowOutOfOrderExecution = true
+
+  let gasLimit = 0n
+  let hasGasLimit = false
+
+  if ('gasLimit' in extraArgs && extraArgs.gasLimit > 0n) {
+    hasGasLimit = true
+    gasLimit = extraArgs.gasLimit
+  }
+
+  const builder = beginCell()
+    .storeUint(Number(EVMExtraArgsV2Tag), 32) // 0x181dcf10
+    .storeBit(hasGasLimit)
+
+  if (hasGasLimit) {
+    builder.storeUint(gasLimit, 256)
+  }
+
+  return builder.storeBit(allowOutOfOrderExecution).endCell()
+}
+
+/**
+ * Builds the Router ccipSend message cell.
+ *
+ * Relies on TL-B structure (Router_CCIPSend) from chainlink-ton repo.
+ */
+export function buildCcipSendCell(
+  destChainSelector: bigint,
+  message: AnyMessage,
+  feeTokenAddress: Address | null = null,
+  queryId = 0n,
+): Cell {
+  // Get receiver bytes and pad to 32 bytes for cross-chain encoding
+  const paddedReceiver = bytesToBuffer(zeroPadValue(getDataBytes(message.receiver), 32))
+
+  // Data cell (ref 0)
+  const dataCell = beginCell()
+    .storeBuffer(bytesToBuffer(message.data || '0x'))
+    .endCell()
+
+  // Token amounts snaked cell (ref 1)
+  const tokenAmountsCell = encodeTokenAmounts(message.tokenAmounts)
+
+  // ExtraArgs cell (ref 2)
+  const extraArgsCell = encodeExtraArgsCell(message.extraArgs)
+
+  return beginCell()
+    .storeUint(CCIP_SEND_OPCODE, 32) // opcode
+    .storeUint(Number(queryId), 64) // queryID
+    .storeUint(destChainSelector, 64) // destChainSelector
+    .storeUint(paddedReceiver.length, 8) // receiver length in bytes
+    .storeBuffer(paddedReceiver) // receiver bytes (32 bytes, left-padded)
+    .storeRef(dataCell) // ref 0: data
+    .storeRef(tokenAmountsCell) // ref 1: tokenAmounts
+    .storeAddress(feeTokenAddress) // null = addr_none for native TON
+    .storeRef(extraArgsCell) // ref 2: extraArgs
+    .endCell()
+}
+
+/**
+ * Gets the fee for sending a CCIP message by calling FeeQuoter.validatedFee.
+ *
+ * @param ctx - Context with TonClient provider and logger
+ * @param router - Router contract address
+ * @param destChainSelector - Destination chain selector
+ * @param message - CCIP message to quote
+ * @returns Fee amount in nanotons
+ */
+export async function getFee(
+  ctx: { provider: TonClient } & WithLogger,
+  router: string,
+  destChainSelector: bigint,
+  message: AnyMessage,
+): Promise<bigint> {
+  const { provider, logger = console } = ctx
+  const routerAddress = Address.parse(router)
+
+  // FeeQuoter requires WRAPPED_NATIVE for native TON
+  const feeTokenAddress = message.feeToken ? Address.parse(message.feeToken) : WRAPPED_NATIVE
+
+  // Get FeeQuoter address via OnRamp
+  let feeQuoterAddress: Address
+  try {
+    const { stack: onRampStack } = await provider.runMethod(routerAddress, 'onRamp', [
+      { type: 'int', value: destChainSelector },
+    ])
+    const onRampAddress = onRampStack.readAddress()
+    logger.debug('OnRamp:', onRampAddress.toString())
+
+    const { stack: feeQuoterStack } = await provider.runMethod(onRampAddress, 'feeQuoter', [
+      { type: 'int', value: destChainSelector },
+    ])
+    feeQuoterAddress = feeQuoterStack.readAddress()
+    logger.debug('FeeQuoter:', feeQuoterAddress.toString())
+  } catch (e) {
+    throw new CCIPError(
+      CCIPErrorCode.CONTRACT_TYPE_INVALID,
+      `Could not get FeeQuoter address: ${e instanceof Error ? e.message : String(e)}`,
+    )
+  }
+
+  // Build stack parameters for validatedFee call
+  const paddedReceiver = bytesToBuffer(zeroPadValue(getDataBytes(message.receiver), 32))
+  const receiverSlice = beginCell().storeBuffer(paddedReceiver).endCell()
+  const dataCell = beginCell()
+    .storeBuffer(bytesToBuffer(message.data || '0x'))
+    .endCell()
+  const tokenAmountsCell = encodeTokenAmounts(message.tokenAmounts)
+  const extraArgsCell = encodeExtraArgsCell(message.extraArgs)
+  const feeTokenSlice = beginCell().storeAddress(feeTokenAddress).endCell()
+
+  const { stack: feeStack } = await provider.runMethod(feeQuoterAddress, 'validatedFee', [
+    { type: 'int', value: 0n },
+    { type: 'int', value: destChainSelector },
+    { type: 'slice', cell: receiverSlice },
+    { type: 'cell', cell: dataCell },
+    { type: 'cell', cell: tokenAmountsCell },
+    { type: 'slice', cell: feeTokenSlice },
+    { type: 'cell', cell: extraArgsCell },
+  ])
+
+  const fee = feeStack.readBigNumber()
+  if (fee < 0n) {
+    throw new CCIPError(CCIPErrorCode.MESSAGE_INVALID, `Invalid fee: ${fee}`)
+  }
+  logger.debug('CCIP fee:', fee.toString(), 'nanotons')
+  return fee
+}
+
+/**
+ * Generates an unsigned CCIP send transaction for the Router.
+ *
+ * @param ctx - Context with TonClient provider and logger
+ * @param _sender - Sender address (unused, for interface compatibility)
+ * @param router - Router contract address
+ * @param destChainSelector - Destination chain selector
+ * @param message - CCIP message with fee included
+ * @param opts - Optional gas buffer override
+ * @returns Unsigned transaction ready for signing
+ */
+export function generateUnsignedCcipSend(
+  ctx: { provider: TonClient } & WithLogger,
+  _sender: string,
+  router: string,
+  destChainSelector: bigint,
+  message: AnyMessage & { fee: bigint },
+  opts?: { gasBuffer?: bigint },
+): Omit<UnsignedTONTx, 'family'> {
+  const { logger = console } = ctx
+  const gasBuffer = opts?.gasBuffer ?? DEFAULT_GAS_BUFFER
+
+  // Router accepts addr_none for native TON (unlike FeeQuoter which needs WRAPPED_NATIVE)
+  const feeTokenAddress = message.feeToken ? Address.parse(message.feeToken) : null
+
+  const ccipSendCell = buildCcipSendCell(destChainSelector, message, feeTokenAddress)
+  const totalValue = message.fee + gasBuffer
+
+  logger.debug('Generating ccipSend tx to router:', router)
+  logger.debug('Total value:', totalValue.toString(), 'nanotons')
+
+  return {
+    to: router,
+    body: ccipSendCell,
+    value: totalValue,
+  }
+}

package/src/ton/types.ts

@@ -3,7 +3,7 @@ import { toBigInt } from 'ethers'
 
 import { CCIPDataFormatUnsupportedError } from '../errors/specialized.ts'
 import type { EVMExtraArgsV2 } from '../extra-args.ts'
-import type { CCIPMessage_V1_6, ChainFamily, ExecutionReport } from '../types.ts'
+import type { CCIPMessage_V1_6, ChainFamily, ExecutionInput } from '../types.ts'
 import { bytesToBuffer } from '../utils.ts'
 
 /** TON-specific CCIP v1.6 message type with EVMExtraArgsV2 (GenericExtraArgsV2) */
@@ -83,7 +83,7 @@ function asSnakeData<T>(array: T[], builderFn: (item: T) => Builder): Cell {
  * @returns BOC-serialized Cell containing the execution report.
  */
 export function serializeExecutionReport(
-  execReport: ExecutionReport<CCIPMessage_V1_6_TON>,
+  execReport: ExecutionInput<CCIPMessage_V1_6_TON>,
 ): Builder {
   return beginCell()
     .storeUint(execReport.message.sourceChainSelector, 64)

package/src/types.ts

@@ -1,8 +1,9 @@
 import type { AbiParametersToPrimitiveTypes, ExtractAbiEvent } from 'abitype'
 import type { BytesLike, Log } from 'ethers'
 
+import type { APICCIPRequestMetadata } from './api/types.ts'
 import type OffRamp_1_6_ABI from './evm/abi/OffRamp_1_6.ts'
-import type { CCIPMessage_EVM, CCIPMessage_V1_6_EVM } from './evm/messages.ts'
+import type { CCIPMessage_EVM, CCIPMessage_V1_6_EVM, CCIPMessage_V2_0 } from './evm/messages.ts'
 import type { ExtraArgs } from './extra-args.ts'
 import type { CCIPMessage_V1_6_Solana } from './solana/types.ts'
 import type { CCIPMessage_V1_6_Sui } from './sui/types.ts'
@@ -87,6 +88,7 @@ export const CCIPVersion = {
   V1_2: '1.2.0',
   V1_5: '1.5.0',
   V1_6: '1.6.0',
+  V2_0: '2.0.0',
 } as const
 /** Type representing one of the supported CCIP versions. */
 export type CCIPVersion = (typeof CCIPVersion)[keyof typeof CCIPVersion]
@@ -104,6 +106,17 @@ type ChainFamilyWithId<F extends ChainFamily> = F extends
 
 /**
  * Network information including chain selector and metadata.
+ *
+ * @example
+ * ```typescript
+ * const info: NetworkInfo = {
+ *   chainSelector: 16015286601757825753n,
+ *   name: 'ethereum-testnet-sepolia',
+ *   networkType: 'TESTNET',
+ *   family: 'EVM',
+ *   chainId: 11155111,
+ * }
+ * ```
  */
 export type NetworkInfo<F extends ChainFamily = ChainFamily> = {
   /** Unique chain selector used by CCIP. */
@@ -116,6 +129,16 @@ export type NetworkInfo<F extends ChainFamily = ChainFamily> = {
 
 /**
  * CCIP lane configuration connecting source and destination chains.
+ *
+ * @example
+ * ```typescript
+ * const lane: Lane = {
+ *   sourceChainSelector: 16015286601757825753n, // Ethereum Sepolia
+ *   destChainSelector: 12532609583862916517n,   // Polygon Mumbai
+ *   onRamp: '0x1234...abcd',
+ *   version: '1.6.0',
+ * }
+ * ```
  */
 export interface Lane<V extends CCIPVersion = CCIPVersion> {
   /** Source chain selector. */
@@ -131,11 +154,11 @@ export interface Lane<V extends CCIPVersion = CCIPVersion> {
 /**
  * Union type representing a CCIP message across different versions and chain families.
  */
-export type CCIPMessage<V extends CCIPVersion = CCIPVersion> = V extends
-  | typeof CCIPVersion.V1_2
-  | typeof CCIPVersion.V1_5
-  ? CCIPMessage_EVM<V>
-  : CCIPMessage_V1_6_EVM | CCIPMessage_V1_6_Solana | CCIPMessage_V1_6_Sui | CCIPMessage_V1_6_TON
+export type CCIPMessage<V extends CCIPVersion = CCIPVersion> = V extends typeof CCIPVersion.V2_0
+  ? CCIPMessage_V2_0
+  : V extends typeof CCIPVersion.V1_6
+    ? CCIPMessage_V1_6_EVM | CCIPMessage_V1_6_Solana | CCIPMessage_V1_6_Sui | CCIPMessage_V1_6_TON
+    : CCIPMessage_EVM<V>
 
 /**
  * Generic log structure compatible across chain families.
@@ -149,6 +172,17 @@ export type Log_ = Pick<Log, 'topics' | 'index' | 'address' | 'blockNumber' | 't
 
 /**
  * Generic transaction structure compatible across chain families.
+ *
+ * @example
+ * ```typescript
+ * const tx: ChainTransaction = {
+ *   hash: '0xabc123...',
+ *   logs: [],
+ *   blockNumber: 12345678,
+ *   timestamp: 1704067200,
+ *   from: '0x1234...abcd',
+ * }
+ * ```
  */
 export type ChainTransaction = {
   /** Transaction hash. */
@@ -171,31 +205,77 @@ export type ChainTransaction = {
 export interface CCIPRequest<V extends CCIPVersion = CCIPVersion> {
   /** Lane configuration for this request. */
   lane: Lane<V>
-  /** The CCIP message being sent. */
   message: CCIPMessage<V>
-  /** Log event from the OnRamp. */
   log: Log_
   /** Transaction that emitted the request. */
   tx: Pick<ChainTransaction, 'hash' | 'logs' | 'blockNumber' | 'timestamp' | 'from' | 'error'>
+
+  /**
+   * API-enriched metadata. Present only when fetched via CCIP API.
+   *
+   * @remarks
+   * When a request is fetched using {@link Chain.getMessageById} or as a fallback
+   * in {@link Chain.getMessagesInTx}, this field contains additional information
+   * including message status, execution details, and network info.
+   *
+   * When constructed from on-chain data only, this field is `undefined`.
+   *
+   * @example
+   * ```typescript
+   * const request = await chain.getMessageById(messageId)
+   * if (request.metadata) {
+   *   console.log('Status:', request.metadata.status)
+   *   console.log('Delivery time:', request.metadata.deliveryTime)
+   * }
+   * ```
+   *
+   * @see {@link APICCIPRequestMetadata}
+   */
+  metadata?: APICCIPRequestMetadata
 }
 
 /**
- * Commit report structure from the OffRamp CommitReportAccepted event.
+ * OnChain Commit report structure from the OffRamp CommitReportAccepted event.
  */
 export type CommitReport = AbiParametersToPrimitiveTypes<
   ExtractAbiEvent<typeof OffRamp_1_6_ABI, 'CommitReportAccepted'>['inputs']
 >[0][number]
 
 /**
- * CCIP commit information containing the report and its log.
+ * OffChain Verification result for a CCIP v2.0 message, returned by the indexer API.
  */
-export interface CCIPCommit {
-  /** The commit report data. */
-  report: CommitReport
-  /** Log event from the commit. */
-  log: Log_
+export type VerifierResult = {
+  /** Verification data required for destination execution (e.g. signatures). */
+  ccvData: BytesLike
+  /** Source CCV contract address. */
+  sourceAddress: string
+  /** Destination CCV contract address. */
+  destAddress: string
+  /** Timestamp of the attestation (Unix seconds). */
+  timestamp?: number
 }
 
+/**
+ * Verification data for a ccip message (onchain CommitReport, or offchain Verifications)
+ */
+export type CCIPVerifications =
+  | {
+      /** The commit report data. */
+      report: CommitReport
+      /** Log event from the commit. */
+      log: Log_
+    }
+  | {
+      /** Policy for this request */
+      verificationPolicy: {
+        optionalCCVs: readonly string[]
+        requiredCCVs: readonly string[]
+        optionalThreshold: number
+      }
+      /** Verifications array; one for each requiredCCV is needed for exec */
+      verifications: VerifierResult[]
+    }
+
 /**
  * Enumeration of possible execution states for a CCIP message.
  */
@@ -231,7 +311,11 @@ export const MessageStatus = {
   Verifying: 'VERIFYING',
   /** Message has been verified by the CCIP network */
   Verified: 'VERIFIED',
-  /** Unknown status returned by API */
+  /**
+   * API returned an unrecognized status value.
+   * This typically means the CCIP API has new status values that this SDK version
+   * doesn't recognize. Consider updating to the latest SDK version.
+   */
   Unknown: 'UNKNOWN',
 } as const
 /** Type representing a CCIP message lifecycle status. */
@@ -254,6 +338,16 @@ export type IntentStatus = (typeof IntentStatus)[keyof typeof IntentStatus]
 
 /**
  * Receipt of a CCIP message execution on the destination chain.
+ *
+ * @example
+ * ```typescript
+ * const receipt: ExecutionReceipt = {
+ *   messageId: '0xabc123...',
+ *   sequenceNumber: 42n,
+ *   state: ExecutionState.Success,
+ *   sourceChainSelector: 16015286601757825753n,
+ * }
+ * ```
  */
 export type ExecutionReceipt = {
   /** Unique message identifier. */
@@ -291,25 +385,59 @@ export type OffchainTokenData = { _tag: string; [k: string]: BytesLike } | undef
 
 /**
  * Execution report containing message, proofs, and offchain token data.
+ *
+ * @example
+ * ```typescript
+ * const report: ExecutionReport = {
+ *   message: { messageId: '0x...', ... },
+ *   proofs: ['0xproof1...', '0xproof2...'],
+ *   proofFlagBits: 0n,
+ *   merkleRoot: '0xroot...',
+ *   offchainTokenData: [],
+ * }
+ * ```
  */
-export type ExecutionReport<M extends CCIPMessage = CCIPMessage> = {
-  /** The CCIP message to execute. */
-  message: M
-  /** Merkle proofs for the message. */
-  proofs: readonly BytesLike[]
-  /** Bit flags for proof verification. */
-  proofFlagBits: bigint
-  /** Merkle root for verification. */
-  merkleRoot: string
-  /** Offchain token data for each token transfer. */
-  offchainTokenData: readonly OffchainTokenData[]
-}
+export type ExecutionInput<M extends CCIPMessage = CCIPMessage> =
+  M extends CCIPMessage<typeof CCIPVersion.V2_0>
+    ? {
+        /** encodedMessage as per CCIPv2 codec */
+        encodedMessage: M['encodedMessage']
+        /** Off-Chain verifications containing verifierResults' ccvData and ccvs addresses */
+        verifications: Pick<VerifierResult, 'ccvData' | 'destAddress'>[]
+      }
+    : {
+        /** The CCIP message to execute. */
+        message: M
+        /** Merkle proofs for the message. */
+        proofs: readonly BytesLike[]
+        /** Bit flags for proof verification. */
+        proofFlagBits: bigint
+        /** Merkle root for verification. */
+        merkleRoot: string
+        /** Offchain token data for each token transfer. */
+        offchainTokenData: readonly OffchainTokenData[]
+      }
 
 /**
  * A message to be sent to another network.
+ *
+ * @example
+ * ```typescript
+ * const message: AnyMessage = {
+ *   receiver: '0x1234...abcd',
+ *   extraArgs: { gasLimit: 200_000n, allowOutOfOrderExecution: true },
+ *   data: '0xdeadbeef',
+ *   tokenAmounts: [{ token: '0xtoken...', amount: 1000000n }],
+ * }
+ * ```
  */
 export type AnyMessage = {
-  /** Receiver address on the destination chain. */
+  /**
+   * Receiver address on the destination chain.
+   * Must be a valid address for the destination chain family. For instance:
+   * - EVM: 20-byte hex (e.g., `0x6d1af98d635d3121286ddda1a0c2d7078b1523ed`)
+   * - Solana: Base58 public key (e.g., `7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV`)
+   */
   receiver: BytesLike
   /** Extra arguments for gas limits and other settings. */
   extraArgs: ExtraArgs
@@ -322,7 +450,22 @@ export type AnyMessage = {
 }
 
 /**
- * Partial [[AnyMessage]], which populates default fields like `extraArgs` if needed
+ * Partial {@link AnyMessage}, which populates default fields like `extraArgs` if needed.
+ *
+ * @example
+ * ```typescript
+ * // Minimal input - only receiver required, defaults applied for extraArgs
+ * const input: MessageInput = {
+ *   receiver: '0x1234...abcd',
+ * }
+ *
+ * // With custom gas limit
+ * const inputWithGas: MessageInput = {
+ *   receiver: '0x1234...abcd',
+ *   extraArgs: { gasLimit: 500_000n },
+ *   data: '0xdeadbeef',
+ * }
+ * ```
  */
 export type MessageInput = Partial<AnyMessage> & {
   receiver: AnyMessage['receiver']