TON Starter Kit Helper Reference

Starter Kit Helpers

The Starter Kit provides helper functions for constructing and sending CCIP messages from TypeScript. These functions abstract TL-B cell encoding and fee estimation.

Extra Args Builders

buildExtraArgsForEVM

Builds a GenericExtraArgsV2 TL-B Cell for a TON → EVM message. The gasLimit is in EVM gas units.

export function buildExtraArgsForEVM(gasLimitEVMUnits: number, allowOutOfOrderExecution: boolean): Cell

Parameters

Returns

A Cell containing the encoded GenericExtraArgsV2 (tag 0x181dcf10).

Example

const extraArgs = buildExtraArgsForEVM(100_000, true) // 100k EVM gas limit

buildExtraArgsForTON

Encodes GenericExtraArgsV2 as ABI bytes for use in an EVM → TON ccipSend call. The gasLimit is in nanoTON.

export function buildExtraArgsForTON(gasLimitNanoTON: bigint | number, allowOutOfOrderExecution: boolean): Uint8Array

Parameters

Returns

A Uint8Array containing the ABI-encoded GenericExtraArgsV2 with the 0x181dcf10 tag prepended.

Example

const extraArgs = buildExtraArgsForTON(100_000_000n, true) // 0.1 TON gas limit

Address Encoding

encodeEVMAddress

Encodes an EVM address (20 bytes) into the 32-byte CrossChainAddress format required by the TON CCIP Router. Left-pads the 20-byte address with 12 zero bytes.

export function encodeEVMAddress(evmAddr: string): Buffer

Parameters

Returns

A 32-byte Buffer (12 zero bytes + 20-byte EVM address).

Example

const receiver = encodeEVMAddress("0xABCD...1234") // 32-byte CrossChainAddress

Message Builders

buildCCIPMessageForEVM

Builds the complete Router_CCIPSend TL-B Cell for a TON → EVM message, ready to send directly to the CCIP Router.

export function buildCCIPMessageForEVM(
  queryID: bigint | number,
  destChainSelector: bigint | number,
  receiverBytes: Buffer,
  data: Cell,
  feeToken: Address,
  extraArgs: Cell
): Cell

Parameters

Returns

A TL-B Cell with opcode 0x31768d95 (Router_CCIPSend).

Example

const ccipSendCell = buildCCIPMessageForEVM(
  BigInt(seqno),
  destChainSelector,
  encodeEVMAddress(evmReceiverAddress),
  beginCell().storeStringTail("Hello EVM from TON").endCell(),
  feeTokenAddress,
  buildExtraArgsForEVM(100_000, true)
)

buildCCIPMessageForTON

Builds the CCIP message struct for an EVM → TON ccipSend call on the EVM Router.

export function buildCCIPMessageForTON(
  receiver: Uint8Array,
  data: Uint8Array,
  gasLimitNanoTON: bigint | number,
  allowOutOfOrderExecution: boolean,
  feeToken: string = ethers.ZeroAddress
): object

Parameters

Returns

A message object ready to pass to the EVM Router's ccipSend function.

Example

const receiverBytes = new Uint8Array(Buffer.from(tonReceiverAddress, "base64"))
const message = buildCCIPMessageForTON(
  receiverBytes,
  ethers.toUtf8Bytes("Hello TON from EVM"),
  100_000_000n, // 0.1 TON
  true,
  ethers.ZeroAddress // pay with native
)

const fee = await router.getFee(destChainSelector, message)
const tx = await router.ccipSend(destChainSelector, message, { value: (fee * 110n) / 100n })

Fee Estimation

getCCIPFeeForEVM

Queries the validated CCIP fee from the TON FeeQuoter for a TON → EVM message. Resolves the FeeQuoter address automatically via the Router and OnRamp getters.

export async function getCCIPFeeForEVM(
  client: TonClient,
  routerAddress: Address,
  destChainSelector: bigint,
  ccipSendMessage: TonCCIPSendMessage
): Promise<bigint>

Parameters

Returns

Promise<bigint> — the fee in nanoTON.

Address resolution: Router.onRamp(destChainSelector) → OnRamp.feeQuoter(destChainSelector) → validatedFeeCell(ccipSendCell)

Example

const fee = await getCCIPFeeForEVM(client, routerAddress, destChainSelector, ccipSendMessage)
const feeWithBuffer = (fee * 110n) / 100n // add 10% buffer

getCCIPFeeForTON

Queries the CCIP fee from the EVM Router for an EVM → TON message.

export async function getCCIPFeeForTON(
  router: ethers.Contract,
  destChainSelector: bigint | number,
  message: ReturnType<typeof buildCCIPMessageForTON>
): Promise<bigint>

Parameters

Returns

Promise<bigint> — the fee in the fee token's smallest unit (e.g., wei for native, or LINK's 18-decimal units).

Event Parsing

extractCCIPMessageIdForTON

Extracts the CCIP messageId from an EVM transaction receipt by parsing the CCIPMessageSent event emitted by the OnRamp.

export function extractCCIPMessageIdForTON(receipt: ethers.TransactionReceipt): string | null

Parameters

Returns

The messageId as a hex string, or null if not found.

Example

const receipt = await tx.wait()
const messageId = extractCCIPMessageIdForTON(receipt)
console.log("CCIP Message ID:", messageId)