@chainlink/ccip-sdk 0.91.0 → 0.92.0

package/src/ton/logs.ts

@@ -0,0 +1,157 @@
+import { Address } from '@ton/core'
+import type { TonClient4 } from '@ton/ton'
+
+import type { LogFilter } from '../chain.ts'
+import { CCIPArgumentInvalidError } from '../errors/specialized.ts'
+import type { Log_ } from '../types.ts'
+
+/** Decoder functions passed to fetchLogs to identify and parse TON log events avoiding circular imports */
+export interface LogDecoders {
+  /** Try to decode as CCIP message, returns messageId if successful */
+  tryDecodeAsMessage: (log: Pick<Log_, 'data'>) => { messageId: string } | undefined
+  /** Try to decode as commit report, returns truthy if successful */
+  tryDecodeAsCommit: (log: Pick<Log_, 'data'>) => unknown[] | undefined
+}
+
+/**
+ * Fetches logs from a TON address by iterating through account transactions.
+ *
+ * Note: For TON, `startBlock` and `endBlock` in opts represent logical time (lt),
+ * not block sequence numbers. This is because TON transaction APIs are indexed by lt.
+ * The lt is monotonically increasing per account and suitable for ordering.
+ *
+ * @param provider - TonClient4 instance
+ * @param opts - Log filter options (startBlock/endBlock are lt values)
+ * @param ltTimestampCache - Cache mapping lt to Unix timestamp
+ * @param decoders - Message decoder functions
+ */
+export async function* fetchLogs(
+  provider: TonClient4,
+  opts: LogFilter,
+  ltTimestampCache: Map<number, number>,
+  decoders: LogDecoders,
+): AsyncIterableIterator<Log_> {
+  if (!opts.address) {
+    throw new CCIPArgumentInvalidError('address', 'Address is required for TON log filtering')
+  }
+
+  const address = Address.parse(opts.address)
+  const searchForward = !!(opts.startBlock || opts.startTime)
+
+  // Get the latest block for account state lookup
+  const lastBlock = await provider.getLastBlock()
+
+  // Get account state to find the last transaction
+  const account = await provider.getAccountLite(lastBlock.last.seqno, address)
+  if (!account.account.last) {
+    return // No transactions
+  }
+
+  // Pagination cursor
+  let cursorLt: bigint = BigInt(account.account.last.lt)
+  let cursorHash: Buffer = Buffer.from(account.account.last.hash, 'base64')
+
+  const collectedLogs: Log_[] = []
+  let isFirstBatch = true
+
+  while (true) {
+    const txs = await provider.getAccountTransactions(address, cursorLt, cursorHash)
+    if (!txs || txs.length === 0) break
+
+    // Skip first tx when paginating (it's the same as last from previous batch)
+    const startIdx = isFirstBatch ? 0 : 1
+    isFirstBatch = false
+
+    for (let i = startIdx; i < txs.length; i++) {
+      const { tx } = txs[i]
+      const txLt = Number(tx.lt)
+      const timestamp = tx.now
+
+      // Cache lt → timestamp
+      ltTimestampCache.set(txLt, timestamp)
+
+      // Range filters
+      if (opts.startBlock && typeof opts.startBlock === 'number' && txLt < opts.startBlock) {
+        if (searchForward) yield* collectedLogs.reverse()
+        return
+      }
+      if (opts.startTime && timestamp < opts.startTime) {
+        if (searchForward) yield* collectedLogs.reverse()
+        return
+      }
+      if (opts.endBlock && typeof opts.endBlock === 'number' && txLt > opts.endBlock) {
+        continue
+      }
+
+      // Extract logs from external-out messages
+      const compositeHash = `${address.toRawString()}:${tx.lt}:${tx.hash().toString('hex')}`
+      let index = 0
+
+      for (const msg of tx.outMessages.values()) {
+        if (msg.info.type !== 'external-out') {
+          index++
+          continue
+        }
+
+        const data = msg.body.toBoc().toString('base64')
+        const topicFilter = opts.topics?.[0]
+
+        // Try to identify log type and build topics array
+        const topics: string[] = []
+
+        if (topicFilter === 'CommitReportAccepted') {
+          // Looking for commits - skip if not a valid commit
+          if (!decoders.tryDecodeAsCommit({ data })) {
+            index++
+            continue
+          }
+          topics.push('CommitReportAccepted')
+        } else {
+          // Try to decode as CCIP message
+          const message = decoders.tryDecodeAsMessage({ data })
+          if (topicFilter && !message) {
+            // Topic filter set but couldn't decode as message - skip
+            index++
+            continue
+          }
+          if (message) {
+            topics.push('CCIPMessageSent')
+          }
+        }
+
+        const log: Log_ = {
+          address: address.toRawString(),
+          topics,
+          data,
+          blockNumber: txLt,
+          transactionHash: compositeHash,
+          index,
+        }
+
+        if (searchForward) {
+          collectedLogs.push(log)
+        } else {
+          yield log
+        }
+        index++
+      }
+    }
+
+    // Update pagination cursor
+    if (txs.length < 2) break
+    const lastTx = txs[txs.length - 1].tx
+    cursorLt = lastTx.lt
+    cursorHash = Buffer.from(lastTx.hash())
+
+    // Early exit if past start boundary
+    if (
+      opts.startBlock &&
+      typeof opts.startBlock === 'number' &&
+      Number(cursorLt) < opts.startBlock
+    )
+      break
+    if (opts.startTime && lastTx.now < opts.startTime) break
+  }
+
+  if (searchForward) yield* collectedLogs.reverse()
+}

package/src/ton/types.ts

@@ -0,0 +1,143 @@
+import { type Builder, Address, Cell, beginCell } from '@ton/core'
+import type { KeyPair } from '@ton/crypto'
+import type { WalletContractV4 } from '@ton/ton'
+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 { bytesToBuffer } from '../utils.ts'
+
+/** TON-specific CCIP v1.6 message type with EVMExtraArgsV2 (GenericExtraArgsV2) */
+export type CCIPMessage_V1_6_TON = CCIPMessage_V1_6 & EVMExtraArgsV2
+
+/** Opcode for OffRamp_ManuallyExecute message on TON */
+export const MANUALLY_EXECUTE_OPCODE = 0xa00785cf
+
+/**
+ * TON wallet with keypair for signing transactions
+ */
+export interface TONWallet {
+  contract: WalletContractV4
+  keyPair: KeyPair
+}
+
+/**
+ * Unsigned TON transaction data.
+ * Contains the payload needed to construct a transaction.
+ * Value is determined at execution time, not included here.
+ */
+export type UnsignedTONTx = {
+  family: typeof ChainFamily.TON
+  /** Target contract address */
+  to: string
+  /** Message payload as BOC-serialized Cell */
+  body: Cell
+}
+
+/** Typeguard for TON Wallet */
+export function isTONWallet(wallet: unknown): wallet is TONWallet {
+  return (
+    typeof wallet === 'object' &&
+    wallet !== null &&
+    'contract' in wallet &&
+    'keyPair' in wallet &&
+    typeof wallet.contract === 'object' &&
+    wallet.contract !== null &&
+    'address' in wallet.contract &&
+    typeof wallet.keyPair === 'object' &&
+    wallet.keyPair !== null &&
+    'secretKey' in wallet.keyPair
+  )
+}
+
+// asSnakeData helper for encoding variable-length arrays
+function asSnakeData<T>(array: T[], builderFn: (item: T) => Builder): Cell {
+  const cells: Builder[] = []
+  let builder = beginCell()
+
+  for (const value of array) {
+    const itemBuilder = builderFn(value)
+    if (itemBuilder.refs > 3) {
+      throw new CCIPDataFormatUnsupportedError(
+        'Cannot pack more than 3 refs per item; store it in a separate ref cell.',
+      )
+    }
+    if (builder.availableBits < itemBuilder.bits || builder.availableRefs <= 1) {
+      cells.push(builder)
+      builder = beginCell()
+    }
+    builder.storeBuilder(itemBuilder)
+  }
+  cells.push(builder)
+
+  // Build the linked structure from the end
+  let current = cells[cells.length - 1].endCell()
+  for (let i = cells.length - 2; i >= 0; i--) {
+    const b = cells[i]
+    b.storeRef(current)
+    current = b.endCell()
+  }
+  return current
+}
+
+/**
+ * Serializes an execution report into a TON Cell for OffRamp execution.
+ * @param execReport - Execution report containing message, proofs, and proof flag bits.
+ * @returns BOC-serialized Cell containing the execution report.
+ */
+export function serializeExecutionReport(
+  execReport: ExecutionReport<CCIPMessage_V1_6_TON>,
+): Builder {
+  return beginCell()
+    .storeUint(execReport.message.sourceChainSelector, 64)
+    .storeRef(asSnakeData([execReport.message], serializeMessage))
+    .storeRef(Cell.EMPTY) // TODO: FIXME: offchainTokenData empty for now, add when implemented
+    .storeRef(
+      asSnakeData(execReport.proofs.map(toBigInt), (proof: bigint) => {
+        return beginCell().storeUint(proof, 256)
+      }),
+    )
+    .storeUint(execReport.proofFlagBits, 256)
+}
+
+function serializeMessage(message: CCIPMessage_V1_6_TON): Builder {
+  return beginCell()
+    .storeUint(BigInt(message.messageId), 256)
+    .storeUint(message.sourceChainSelector, 64)
+    .storeUint(message.destChainSelector, 64)
+    .storeUint(message.sequenceNumber, 64)
+    .storeUint(message.nonce, 64)
+    .storeRef(
+      beginCell()
+        .storeUint(bytesToBuffer(message.sender).length, 8)
+        .storeBuffer(bytesToBuffer(message.sender))
+        .endCell(),
+    )
+    .storeRef(beginCell().storeBuffer(bytesToBuffer(message.data)).endCell())
+    .storeAddress(Address.parse(message.receiver))
+    .storeCoins(message.gasLimit)
+    .storeMaybeRef(
+      message.tokenAmounts?.length > 0 ? serializeTokenAmounts(message.tokenAmounts) : null,
+    )
+}
+
+function serializeTokenAmounts(tokenAmounts: CCIPMessage_V1_6['tokenAmounts']): Cell {
+  const builder = beginCell()
+  for (const ta of tokenAmounts) {
+    builder.storeRef(
+      beginCell()
+        .storeRef(serializeSourcePool(ta.sourcePoolAddress))
+        .storeAddress(Address.parse(ta.destTokenAddress))
+        .storeUint(BigInt(ta.amount), 256)
+        .storeRef(beginCell().storeBuffer(bytesToBuffer(ta.extraData)).endCell())
+        .endCell(),
+    )
+  }
+  return builder.endCell()
+}
+
+function serializeSourcePool(address: string): Cell {
+  const bytes = bytesToBuffer(address)
+  return beginCell().storeUint(bytes.length, 8).storeBuffer(bytes).endCell()
+}