@chainlink/ccip-sdk 0.94.0 → 0.96.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/utils.ts

@@ -2,7 +2,7 @@ import { Cell, Dictionary, beginCell } from '@ton/core'
 import { hexlify, toBeHex } from 'ethers'
 
 import { CCIPTransactionNotFoundError } from '../errors/specialized.ts'
-import type { WithLogger } from '../types.ts'
+import { type WithLogger, NetworkType } from '../types.ts'
 import { bytesToBuffer } from '../utils.ts'
 
 /**
@@ -340,14 +340,14 @@ export async function parseJettonContent(
  * TonCenter V3 provides an index that allows hash-only lookups.
  *
  * @param hash - Raw 64-char hex transaction hash
- * @param isTestnet - Whether to use testnet API
+ * @param networkType - Network type (mainnet or testnet)
  * @param fetch - Rate-limited fetch function
  * @param logger - Logger instance
  * @returns Transaction identifier components needed for V4 API lookup
  */
 export async function lookupTxByRawHash(
   hash: string,
-  isTestnet: boolean,
+  networkType: NetworkType,
   fetch = globalThis.fetch,
   { logger = console }: WithLogger = {},
 ): Promise<{
@@ -355,9 +355,10 @@ export async function lookupTxByRawHash(
   lt: string
   hash: string
 }> {
-  const baseUrl = isTestnet
-    ? 'https://testnet.toncenter.com/api/v3/transactions'
-    : 'https://toncenter.com/api/v3/transactions'
+  const baseUrl =
+    networkType === NetworkType.Mainnet
+      ? 'https://toncenter.com/api/v3/transactions'
+      : 'https://testnet.toncenter.com/api/v3/transactions'
 
   // TonCenter V3 accepts hex directly
   const cleanHash = bytesToBuffer(hash).toString('hex')

package/src/types.ts

@@ -1,6 +1,7 @@
 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 { ExtraArgs } from './extra-args.ts'
@@ -60,15 +61,26 @@ export type MergeArrayElements<T, U> = {
  * Enumeration of supported blockchain families.
  */
 export const ChainFamily = {
-  EVM: 'evm',
-  Solana: 'solana',
-  Aptos: 'aptos',
-  Sui: 'sui',
-  TON: 'ton',
+  EVM: 'EVM',
+  Solana: 'SVM',
+  Aptos: 'APTOS',
+  Sui: 'SUI',
+  TON: 'TON',
+  Unknown: 'UNKNOWN',
 } as const
 /** Type representing one of the supported chain families. */
 export type ChainFamily = (typeof ChainFamily)[keyof typeof ChainFamily]
 
+/**
+ * Enumeration of network types (mainnet vs testnet).
+ */
+export const NetworkType = {
+  Mainnet: 'MAINNET',
+  Testnet: 'TESTNET',
+} as const
+/** Type representing the network environment type. */
+export type NetworkType = (typeof NetworkType)[keyof typeof NetworkType]
+
 /**
  * Enumeration of supported CCIP protocol versions.
  */
@@ -88,23 +100,44 @@ type ChainFamilyWithId<F extends ChainFamily> = F extends
   : F extends typeof ChainFamily.Solana
     ? { readonly family: F; readonly chainId: string }
     : F extends typeof ChainFamily.Aptos | typeof ChainFamily.Sui
-      ? { readonly family: F; readonly chainId: `${F}:${number}` }
+      ? { readonly family: F; readonly chainId: `${Lowercase<F>}:${number}` }
       : never
 
 /**
  * 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. */
   readonly chainSelector: bigint
   /** Human-readable network name. */
   readonly name: string
-  /** Whether this is a testnet. */
-  readonly isTestnet: boolean
+  /** Network environment type. */
+  readonly networkType: NetworkType
 } & ChainFamilyWithId<F>
 
 /**
  * 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. */
@@ -138,6 +171,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. */
@@ -166,6 +210,29 @@ export interface CCIPRequest<V extends CCIPVersion = CCIPVersion> {
   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
 }
 
 /**
@@ -216,6 +283,12 @@ export const MessageStatus = {
   Success: 'SUCCESS',
   /** Message execution failed on destination. */
   Failed: 'FAILED',
+  /** Message is being verified by the CCIP network */
+  Verifying: 'VERIFYING',
+  /** Message has been verified by the CCIP network */
+  Verified: 'VERIFIED',
+  /** Unknown status returned by API */
+  Unknown: 'UNKNOWN',
 } as const
 /** Type representing a CCIP message lifecycle status. */
 export type MessageStatus = (typeof MessageStatus)[keyof typeof MessageStatus]
@@ -237,6 +310,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. */
@@ -274,6 +357,17 @@ 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. */
@@ -290,6 +384,16 @@ export type ExecutionReport<M extends CCIPMessage = CCIPMessage> = {
 
 /**
  * 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. */
@@ -305,7 +409,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']