@chainlink/ccip-sdk 0.95.0 → 0.97.0

package/src/ton/index.ts

@@ -8,9 +8,11 @@ import { type Memoized, memoize } from 'micro-memoize'
 import type { PickDeep } from 'type-fest'
 
 import { streamTransactionsForAddress } from './logs.ts'
+import { generateUnsignedCcipSend, getFee as getFeeImpl } from './send.ts'
 import { type ChainContext, type GetBalanceOpts, type LogFilter, Chain } from '../chain.ts'
 import {
   CCIPArgumentInvalidError,
+  CCIPExecutionReportChainMismatchError,
   CCIPExtraArgsInvalidError,
   CCIPHttpError,
   CCIPNotImplementedError,
@@ -19,21 +21,24 @@ import {
   CCIPTopicsInvalidError,
   CCIPTransactionNotFoundError,
   CCIPWalletInvalidError,
-} from '../errors/specialized.ts'
+} from '../errors/index.ts'
 import { type EVMExtraArgsV2, type ExtraArgs, EVMExtraArgsV2Tag } from '../extra-args.ts'
+import type { LeafHasher } from '../hasher/common.ts'
+import { buildMessageForDest, getMessagesInBatch } from '../requests.ts'
 import { supportedChains } from '../supported-chains.ts'
 import {
   type CCIPExecution,
   type CCIPRequest,
   type ChainTransaction,
   type CommitReport,
+  type ExecutionInput,
   type ExecutionReceipt,
-  type ExecutionReport,
   type Lane,
   type Log_,
   type NetworkInfo,
   type OffchainTokenData,
   type WithLogger,
+  CCIPVersion,
   ChainFamily,
   ExecutionState,
 } from '../types.ts'
@@ -45,11 +50,10 @@ import {
   parseTypeAndVersion,
   sleep,
 } from '../utils.ts'
-import { generateUnsignedExecuteReport as generateUnsignedExecuteReportImpl } from './exec.ts'
+import { generateUnsignedExecuteReport } from './exec.ts'
 import { getTONLeafHasher } from './hasher.ts'
 import { type CCIPMessage_V1_6_TON, type UnsignedTONTx, isTONWallet } from './types.ts'
 import { crc32, lookupTxByRawHash, parseJettonContent } from './utils.ts'
-import type { LeafHasher } from '../hasher/common.ts'
 export type { TONWallet, UnsignedTONTx } from './types.ts'
 
 /**
@@ -179,6 +183,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
    * @param url - RPC endpoint URL for TonClient (v2).
    * @param ctx - Context containing logger.
    * @returns A new TONChain instance.
+   * @throws {@link CCIPHttpError} if connection to the RPC endpoint fails
    */
   static async fromUrl(url: string, ctx?: ChainContext): Promise<TONChain> {
     const { logger = console } = ctx ?? {}
@@ -219,6 +224,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
    *
    * @param block - Logical time (lt) as number, or 'finalized' for latest block timestamp
    * @returns Unix timestamp in seconds
+   * @throws {@link CCIPNotImplementedError} if lt is not in cache
    */
   async getBlockTimestamp(block: number | 'finalized'): Promise<number> {
     if (typeof block != 'number') {
@@ -246,6 +252,8 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
    * @param tx - Transaction identifier in either format
    * @returns ChainTransaction with transaction details
    *          Note: `blockNumber` contains logical time (lt), not block seqno
+   * @throws {@link CCIPArgumentInvalidError} if hash format is invalid
+   * @throws {@link CCIPTransactionNotFoundError} if transaction not found
    */
   async getTransaction(tx: string | Transaction): Promise<ChainTransaction> {
     let address
@@ -340,6 +348,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
    * not block sequence numbers. This is because TON transaction APIs are indexed by lt.
    *
    * @param opts - Log filter options (startBlock/endBlock are interpreted as lt values)
+   * @throws {@link CCIPTopicsInvalidError} if topics format is invalid
    */
   async *getLogs(opts: LogFilter): AsyncIterableIterator<Log_> {
     let topics
@@ -369,11 +378,11 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
       'lane' | `log.${'topics' | 'address' | 'blockNumber'}` | 'message.sequenceNumber'
     >,
   >(
-    _request: R,
-    _commit: Pick<CommitReport, 'minSeqNr' | 'maxSeqNr'>,
-    _opts?: { page?: number },
+    request: R,
+    range: Pick<CommitReport, 'minSeqNr' | 'maxSeqNr'>,
+    opts?: Pick<LogFilter, 'page'>,
   ): Promise<R['message'][]> {
-    return Promise.reject(new CCIPNotImplementedError('getMessagesInBatch'))
+    return getMessagesInBatch(this, request, range, opts)
   }
 
   /** {@inheritDoc Chain.typeAndVersion} */
@@ -420,9 +429,14 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     return stack.readAddress().toRawString()
   }
 
-  /** {@inheritDoc Chain.getNativeTokenForRouter} */
+  /**
+   * {@inheritDoc Chain.getNativeTokenForRouter}
+   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
+   */
   getNativeTokenForRouter(_router: string): Promise<string> {
-    return Promise.reject(new CCIPNotImplementedError('getNativeTokenForRouter'))
+    // TON native token is represented as address 0:0...01 (workchain 0, hash = 1)
+    // This is a convention for representing native TON in CCIP
+    return Promise.resolve('0:0000000000000000000000000000000000000000000000000000000000000001')
   }
 
   /** {@inheritDoc Chain.getOffRampsForRouter} */
@@ -445,8 +459,11 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     return stack.readAddress().toRawString()
   }
 
-  /** {@inheritDoc Chain.getOnRampForOffRamp} */
-  async getOnRampForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string> {
+  /**
+   * {@inheritDoc Chain.getOnRampsForOffRamp}
+   * @throws {@link CCIPSourceChainUnsupportedError} if source chain is not configured
+   */
+  async getOnRampsForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string[]> {
     try {
       const offRampContract = this.provider.provider(Address.parse(offRamp))
 
@@ -474,7 +491,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
         const onRampLength = onRampSlice.loadUint(8)
         onRamp = onRampSlice.loadBuffer(onRampLength)
       }
-      return decodeAddress(onRamp, networkInfo(sourceChainSelector).family)
+      return [decodeAddress(onRamp, networkInfo(sourceChainSelector).family)]
     } catch (error) {
       if (isTvmError(error) && error.exitCode === 266) {
         throw new CCIPSourceChainUnsupportedError(sourceChainSelector, {
@@ -485,13 +502,10 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     }
   }
 
-  /** {@inheritDoc Chain.getCommitStoreForOffRamp} */
-  async getCommitStoreForOffRamp(offRamp: string): Promise<string> {
-    // TODO: FIXME: check assumption
-    return Promise.resolve(offRamp)
-  }
-
-  /** {@inheritDoc Chain.getTokenForTokenPool} */
+  /**
+   * {@inheritDoc Chain.getTokenForTokenPool}
+   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
+   */
   async getTokenForTokenPool(_tokenPool: string): Promise<string> {
     return Promise.reject(new CCIPNotImplementedError('getTokenForTokenPool'))
   }
@@ -519,12 +533,45 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     }
   }
 
-  /** {@inheritDoc Chain.getBalance} */
-  async getBalance(_opts: GetBalanceOpts): Promise<bigint> {
-    return Promise.reject(new CCIPNotImplementedError('TONChain.getBalance'))
+  /**
+   * {@inheritDoc Chain.getBalance}
+   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
+   */
+  async getBalance(opts: GetBalanceOpts): Promise<bigint> {
+    const { holder, token } = opts
+    const holderAddress = Address.parse(holder)
+
+    if (!token) {
+      // Get native TON balance
+      const state = await this.provider.getContractState(holderAddress)
+      return state.balance
+    }
+
+    // For jetton balance, we need to:
+    // 1. Derive the jetton wallet address for this holder
+    // 2. Query the balance from that wallet contract
+    const jettonMaster = Address.parse(token)
+    const { stack } = await this.provider.runMethod(jettonMaster, 'get_wallet_address', [
+      { type: 'slice', cell: beginCell().storeAddress(holderAddress).endCell() },
+    ])
+    const jettonWalletAddress = stack.readAddress()
+
+    try {
+      const { stack: balanceStack } = await this.provider.runMethod(
+        jettonWalletAddress,
+        'get_wallet_data',
+      )
+      return balanceStack.readBigNumber() // First value is balance
+    } catch {
+      // Wallet doesn't exist yet = 0 balance
+      return 0n
+    }
   }
 
-  /** {@inheritDoc Chain.getTokenAdminRegistryFor} */
+  /**
+   * {@inheritDoc Chain.getTokenAdminRegistryFor}
+   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
+   */
   getTokenAdminRegistryFor(_address: string): Promise<string> {
     return Promise.reject(new CCIPNotImplementedError('getTokenAdminRegistryFor'))
   }
@@ -562,7 +609,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
       }
 
       // Load sender address
-      const sender = slice.loadAddress().toString()
+      const sender = slice.loadAddress().toRawString()
 
       // Load body cell ref
       const bodyCell = slice.loadRef()
@@ -609,10 +656,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
       const allowOutOfOrderExecution = extraArgsSlice.loadBit()
 
       // Build extraArgs as raw hex matching reference format
-      const tagHex = extraArgsTag.toString(16).padStart(8, '0')
-      const gasLimitHex = (hasGasLimit ? '8' : '0') + gasLimit.toString(16).padStart(63, '0')
-      const oooByte = allowOutOfOrderExecution ? '40' : '00'
-      const extraArgs = '0x' + tagHex + gasLimitHex + oooByte
+      const extraArgs = '0x' + extraArgsCell.toBoc().toString('hex')
 
       // Load tokenAmounts from ref 3
       const _tokenAmountsCell = bodySlice.loadRef()
@@ -777,7 +821,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
    * - sourceChainSelector: uint64 (8 bytes)
    * - sequenceNumber: uint64 (8 bytes)
    * - messageId: uint256 (32 bytes)
-   * - state: uint8 (1 byte) - Untouched=0, InProgress=1, Success=2, Failure=3
+   * - state: uint8 (1 byte) - InProgress=1, Success=2, Failed=3
    *
    * @param log - Log with data field (base64-encoded BOC).
    * @returns ExecutionReceipt or undefined if not valid.
@@ -832,6 +876,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
    * and raw format strings ("workchain:hash").
    * @param bytes - Bytes or string to convert.
    * @returns TON raw address string in format "workchain:hash".
+   * @throws {@link CCIPArgumentInvalidError} if bytes length is invalid
    */
   static getAddress(bytes: BytesLike): string {
     // If it's already a string address, try to parse and return raw format
@@ -951,20 +996,107 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
   }
 
   /** {@inheritDoc Chain.getFee} */
-  async getFee(_opts: Parameters<Chain['getFee']>[0]): Promise<bigint> {
-    return Promise.reject(new CCIPNotImplementedError('getFee'))
+  async getFee({
+    router,
+    destChainSelector,
+    message,
+  }: Parameters<Chain['getFee']>[0]): Promise<bigint> {
+    return getFeeImpl(
+      this,
+      router,
+      destChainSelector,
+      buildMessageForDest(message, networkInfo(destChainSelector).family),
+    )
   }
 
   /** {@inheritDoc Chain.generateUnsignedSendMessage} */
-  generateUnsignedSendMessage(
-    _opts: Parameters<Chain['generateUnsignedSendMessage']>[0],
-  ): Promise<never> {
-    return Promise.reject(new CCIPNotImplementedError('generateUnsignedSendMessage'))
+  async generateUnsignedSendMessage({
+    router,
+    destChainSelector,
+    message,
+    sender,
+  }: Parameters<Chain['generateUnsignedSendMessage']>[0]): Promise<UnsignedTONTx> {
+    // Convert MessageInput to AnyMessage with defaults
+    const populatedMessage = buildMessageForDest(message, networkInfo(destChainSelector).family)
+
+    // Calculate fee if not provided
+    const fee =
+      message.fee ??
+      (await this.getFee({
+        router,
+        destChainSelector,
+        message: populatedMessage,
+      }))
+
+    const unsigned = generateUnsignedCcipSend(this, sender, router, destChainSelector, {
+      ...populatedMessage,
+      fee,
+    })
+
+    return {
+      family: ChainFamily.TON,
+      ...unsigned,
+    }
   }
 
   /** {@inheritDoc Chain.sendMessage} */
-  async sendMessage(_opts: Parameters<Chain['sendMessage']>[0]): Promise<CCIPRequest> {
-    return Promise.reject(new CCIPNotImplementedError('sendMessage'))
+  async sendMessage({
+    router,
+    destChainSelector,
+    message,
+    wallet,
+  }: Parameters<Chain['sendMessage']>[0]): Promise<CCIPRequest> {
+    if (!isTONWallet(wallet)) {
+      throw new CCIPWalletInvalidError(wallet)
+    }
+
+    const sender = await wallet.getAddress()
+
+    // Generate unsigned transaction with fee calculation if needed
+    const { family: _, ...unsigned } = await this.generateUnsignedSendMessage({
+      router,
+      destChainSelector,
+      message,
+      sender,
+    })
+
+    // Send transaction
+    const startTime = Math.floor(Date.now() / 1000)
+    const seqno = await wallet.sendTransaction(unsigned)
+
+    this.logger.info('CCIP send transaction submitted, seqno:', seqno)
+
+    // Wait for CCIPMessageSent event and extract the request
+    // Query the OnRamp for the CCIPMessageSent event
+    const onRamp = await this.getOnRampForRouter(router, destChainSelector)
+
+    // Poll for the message in recent logs
+    for await (const log of this.getLogs({
+      address: onRamp,
+      topics: [crc32('CCIPMessageSent')],
+      startTime,
+      watch: sleep(5 * 60e3 /* 5m timeout */),
+    })) {
+      const msg = TONChain.decodeMessage(log)
+      if (!msg) continue
+
+      // Found our message: construct and return the CCIPRequest
+      const tx = log.tx ?? (await this.getTransaction(log.transactionHash))
+
+      return {
+        lane: {
+          sourceChainSelector: this.network.chainSelector,
+          destChainSelector,
+          onRamp,
+          version: CCIPVersion.V1_6,
+        },
+        message: msg,
+        log,
+        tx,
+      }
+    }
+
+    throw new CCIPTransactionNotFoundError(seqno.toString())
   }
 
   /** {@inheritDoc Chain.getOffchainTokenData} */
@@ -972,19 +1104,28 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     return Promise.resolve(request.message.tokenAmounts.map(() => undefined))
   }
 
-  /** {@inheritDoc Chain.generateUnsignedExecuteReport} */
-  generateUnsignedExecuteReport({
-    offRamp,
-    execReport,
-    ...opts
-  }: Parameters<Chain['generateUnsignedExecuteReport']>[0]): Promise<UnsignedTONTx> {
-    if (!('allowOutOfOrderExecution' in execReport.message && 'gasLimit' in execReport.message)) {
+  /**
+   * {@inheritDoc Chain.generateUnsignedExecute}
+   * @throws {@link CCIPExtraArgsInvalidError} if extra args are not EVMExtraArgsV2 format
+   */
+  generateUnsignedExecute(
+    opts: Parameters<Chain['generateUnsignedExecute']>[0],
+  ): Promise<UnsignedTONTx> {
+    if (
+      !(
+        'input' in opts &&
+        'message' in opts.input &&
+        'allowOutOfOrderExecution' in opts.input.message &&
+        'gasLimit' in opts.input.message
+      )
+    ) {
       throw new CCIPExtraArgsInvalidError('TON')
     }
+    const { offRamp, input } = opts
 
-    const unsigned = generateUnsignedExecuteReportImpl(
+    const unsigned = generateUnsignedExecuteReport(
       offRamp,
-      execReport as ExecutionReport<CCIPMessage_V1_6_TON>,
+      input as ExecutionInput<CCIPMessage_V1_6_TON>,
       opts,
     )
 
@@ -994,15 +1135,21 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     })
   }
 
-  /** {@inheritDoc Chain.executeReport} */
-  async executeReport(opts: Parameters<Chain['executeReport']>[0]): Promise<CCIPExecution> {
+  /**
+   * {@inheritDoc Chain.execute}
+   * @throws {@link CCIPWalletInvalidError} if wallet is not a valid TON wallet
+   * @throws {@link CCIPReceiptNotFoundError} if execution receipt not found within timeout
+   */
+  async execute(opts: Parameters<Chain['execute']>[0]): Promise<CCIPExecution> {
+    if (!('input' in opts && 'message' in opts.input))
+      throw new CCIPExecutionReportChainMismatchError('TON')
     const { offRamp, wallet } = opts
     if (!isTONWallet(wallet)) {
       throw new CCIPWalletInvalidError(wallet)
     }
     const payer = await wallet.getAddress()
 
-    const { family: _, ...unsigned } = await this.generateUnsignedExecuteReport({
+    const { family: _, ...unsigned } = await this.generateUnsignedExecute({
       ...opts,
       payer,
     })
@@ -1014,7 +1161,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
       ...unsigned,
     })
 
-    const message = opts.execReport.message as CCIPMessage_V1_6_TON
+    const message = opts.input.message as CCIPMessage_V1_6_TON
     for await (const exec of this.getExecutionReceipts({
       offRamp,
       messageId: message.messageId,
@@ -1039,27 +1186,42 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     }
   }
 
-  /** {@inheritDoc Chain.getSupportedTokens} */
+  /**
+   * {@inheritDoc Chain.getSupportedTokens}
+   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
+   */
   async getSupportedTokens(_address: string): Promise<string[]> {
     return Promise.reject(new CCIPNotImplementedError('getSupportedTokens'))
   }
 
-  /** {@inheritDoc Chain.getRegistryTokenConfig} */
+  /**
+   * {@inheritDoc Chain.getRegistryTokenConfig}
+   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
+   */
   async getRegistryTokenConfig(_address: string, _tokenName: string): Promise<never> {
     return Promise.reject(new CCIPNotImplementedError('getRegistryTokenConfig'))
   }
 
-  /** {@inheritDoc Chain.getTokenPoolConfigs} */
-  async getTokenPoolConfigs(_tokenPool: string): Promise<never> {
-    return Promise.reject(new CCIPNotImplementedError('getTokenPoolConfigs'))
+  /**
+   * {@inheritDoc Chain.getTokenPoolConfig}
+   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
+   */
+  async getTokenPoolConfig(_tokenPool: string): Promise<never> {
+    return Promise.reject(new CCIPNotImplementedError('getTokenPoolConfig'))
   }
 
-  /** {@inheritDoc Chain.getTokenPoolRemotes} */
+  /**
+   * {@inheritDoc Chain.getTokenPoolRemotes}
+   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
+   */
   async getTokenPoolRemotes(_tokenPool: string): Promise<never> {
     return Promise.reject(new CCIPNotImplementedError('getTokenPoolRemotes'))
   }
 
-  /** {@inheritDoc Chain.getFeeTokens} */
+  /**
+   * {@inheritDoc Chain.getFeeTokens}
+   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
+   */
   async getFeeTokens(_router: string): Promise<never> {
     return Promise.reject(new CCIPNotImplementedError('getFeeTokens'))
   }