Basic TON Chain support for CCIP SDK

ccip-cli/src/providers/index.ts

@@ -13,6 +13,7 @@ import {
 import { loadAptosWallet } from './aptos.ts'
 import { loadEvmWallet } from './evm.ts'
 import { loadSolanaWallet } from './solana.ts'
+import { loadTonWallet } from './ton.ts'
 import type { Ctx } from '../commands/index.ts'
 
 const RPCS_RE = /\b(?:http|ws)s?:\/\/[\w/\\@&?%~#.,;:=+-]+/
@@ -187,6 +188,9 @@ export async function loadChainWallet(chain: Chain, opts: { wallet?: unknown })
     case ChainFamily.Aptos:
       wallet = await loadAptosWallet(opts)
       return [wallet.accountAddress.toString(), wallet] as const
+    case ChainFamily.TON:
+      wallet = await loadTonWallet(opts)
+      return [wallet.contract.address.toString(), wallet] as const
     default:
       throw new Error(`Unsupported chain family: ${chain.network.family}`)
   }

ccip-cli/src/providers/ton.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from 'node:fs'
+import util from 'node:util'
+
+import type { TONWallet } from '@chainlink/ccip-sdk/src/ton/types.ts'
+import { keyPairFromSecretKey, mnemonicToPrivateKey } from '@ton/crypto'
+import { WalletContractV4 } from '@ton/ton'
+
+/**
+ * Loads a TON wallet from the provided options.
+ * @param wallet - wallet options (as passed from yargs argv)
+ * @returns Promise to TONWallet instance
+ */
+export async function loadTonWallet({
+  wallet: walletOpt,
+}: { wallet?: unknown } = {}): Promise<TONWallet> {
+  if (!walletOpt) walletOpt = process.env['USER_KEY'] || process.env['OWNER_KEY']
+
+  if (typeof walletOpt !== 'string')
+    throw new Error(`Invalid wallet option: ${util.inspect(walletOpt)}`)
+
+  // Handle mnemonic phrase
+  if (walletOpt.includes(' ')) {
+    const mnemonic = walletOpt.trim().split(' ')
+    const keyPair = await mnemonicToPrivateKey(mnemonic)
+    const contract = WalletContractV4.create({
+      workchain: 0,
+      publicKey: keyPair.publicKey,
+    })
+    return { contract, keyPair }
+  }
+
+  // Handle hex private key
+  if (walletOpt.startsWith('0x')) {
+    const secretKey = Buffer.from(walletOpt.slice(2), 'hex')
+    if (secretKey.length === 32) {
+      throw new Error(
+        'Invalid private key: 32-byte seeds not supported. Use 64-byte secret key or mnemonic.',
+      )
+    }
+    if (secretKey.length !== 64) {
+      throw new Error('Invalid private key: must be 64 bytes (or use mnemonic)')
+    }
+    const keyPair = keyPairFromSecretKey(secretKey)
+    const contract = WalletContractV4.create({
+      workchain: 0,
+      publicKey: keyPair.publicKey,
+    })
+    return { contract, keyPair }
+  }
+
+  // Handle file path
+  if (existsSync(walletOpt)) {
+    const content = readFileSync(walletOpt, 'utf8').trim()
+    const secretKey = Buffer.from(content.startsWith('0x') ? content.slice(2) : content, 'hex')
+    if (secretKey.length !== 64) {
+      throw new Error('Invalid private key in file: must be 64 bytes')
+    }
+    const keyPair = keyPairFromSecretKey(secretKey)
+    const contract = WalletContractV4.create({
+      workchain: 0,
+      publicKey: keyPair.publicKey,
+    })
+    return { contract, keyPair }
+  }
+
+  throw new Error('Wallet not specified')
+}

ccip-sdk/package.json

@@ -55,6 +55,8 @@
     "@mysten/sui": "^1.45.2",
     "@solana/spl-token": "0.4.14",
     "@solana/web3.js": "^1.98.4",
+    "@ton/core": "0.62.0",
+    "@ton/ton": "^16.1.0",
     "abitype": "1.2.1",
     "bn.js": "^5.2.2",
     "borsh": "^2.0.0",
@@ -68,4 +70,4 @@
     "bigint-buffer": "npm:@trufflesuite/[email protected]",
     "axios": "^1.13.2"
   }
-}
+}

ccip-sdk/src/chain.ts

@@ -13,6 +13,7 @@ import type {
 } from './extra-args.ts'
 import type { LeafHasher } from './hasher/common.ts'
 import type { UnsignedSolanaTx } from './solana/types.ts'
+import type { UnsignedTONTx } from './ton/types.ts'
 import {
   type AnyMessage,
   type CCIPCommit,
@@ -100,6 +101,7 @@ export type UnsignedTx = {
   [ChainFamily.EVM]: UnsignedEVMTx
   [ChainFamily.Solana]: UnsignedSolanaTx
   [ChainFamily.Aptos]: UnsignedAptosTx
+  [ChainFamily.TON]: UnsignedTONTx
   [ChainFamily.Sui]: never // TODO
 }
 

ccip-sdk/src/extra-args.test.ts

@@ -5,7 +5,8 @@ import { dataSlice, getNumber } from 'ethers'
 
 // Import index.ts to ensure all Chain classes are loaded and registered
 import './index.ts'
-import { decodeExtraArgs, encodeExtraArgs } from './extra-args.ts'
+import { EVMExtraArgsV2Tag, decodeExtraArgs, encodeExtraArgs } from './extra-args.ts'
+import { extractMagicTag } from './ton/utils.ts'
 import { ChainFamily } from './types.ts'
 
 describe('encodeExtraArgs', () => {
@@ -74,6 +75,40 @@ describe('encodeExtraArgs', () => {
       assert.equal(encoded.length, 2 + 2 * (4 + 32 + 1)) // Much shorter than EVM encoding
     })
   })
+  describe('TON extra args', () => {
+    it('should encode EVMExtraArgsV2 (GenericExtraArgsV2)', () => {
+      const encoded = encodeExtraArgs(
+        { gasLimit: 400_000n, allowOutOfOrderExecution: true },
+        ChainFamily.TON,
+      )
+
+      assert.equal(extractMagicTag(encoded), EVMExtraArgsV2Tag)
+      assert.ok(encoded.length > 10)
+    })
+
+    it('should encode EVMExtraArgsV2 (GenericExtraArgsV2) with allowOutOfOrderExecution false', () => {
+      const encoded = encodeExtraArgs(
+        { gasLimit: 500_000n, allowOutOfOrderExecution: false },
+        ChainFamily.TON,
+      )
+
+      assert.equal(extractMagicTag(encoded), EVMExtraArgsV2Tag)
+      assert.ok(encoded.length > 10)
+    })
+
+    it('should parse real Sepolia->TON message extraArgs', () => {
+      // https://sepolia.etherscan.io/tx/0x6bdfcce8def68f19f40d340bc38d01866c10a4c92685df1c3d08180280a4ccac
+      const res = decodeExtraArgs(
+        '0x181dcf100000000000000000000000000000000000000000000000000000000005f5e1000000000000000000000000000000000000000000000000000000000000000001',
+        ChainFamily.EVM,
+      )
+      assert.deepEqual(res, {
+        _tag: 'EVMExtraArgsV2',
+        gasLimit: 100_000_000n,
+        allowOutOfOrderExecution: true,
+      })
+    })
+  })
 })
 
 describe('parseExtraArgs', () => {
@@ -138,6 +173,33 @@ describe('parseExtraArgs', () => {
       })
     })
   })
+  describe('TON extra args (TLB encoding)', () => {
+    it('should parse EVMExtraArgsV2 (GenericExtraArgsV2)', () => {
+      const encoded = encodeExtraArgs(
+        { gasLimit: 400_000n, allowOutOfOrderExecution: true },
+        ChainFamily.TON,
+      )
+      const res = decodeExtraArgs(encoded, ChainFamily.TON)
+      assert.deepEqual(res, {
+        _tag: 'EVMExtraArgsV2',
+        gasLimit: 400000n,
+        allowOutOfOrderExecution: true,
+      })
+    })
+
+    it('should parse EVMExtraArgsV2 (GenericExtraArgsV2) with allowOutOfOrderExecution false', () => {
+      const encoded = encodeExtraArgs(
+        { gasLimit: 500_000n, allowOutOfOrderExecution: false },
+        ChainFamily.TON,
+      )
+      const res = decodeExtraArgs(encoded, ChainFamily.TON)
+      assert.deepEqual(res, {
+        _tag: 'EVMExtraArgsV2',
+        gasLimit: 500000n,
+        allowOutOfOrderExecution: false,
+      })
+    })
+  })
 
   describe('auto-detect chain family', () => {
     it('should auto-detect EVM v1 args', () => {
@@ -196,6 +258,13 @@ describe('parseExtraArgs', () => {
       const decoded = decodeExtraArgs(encoded, ChainFamily.Aptos)
       assert.deepEqual(decoded, { ...original, _tag: 'EVMExtraArgsV2' })
     })
+
+    it('should round-trip TON EVMExtraArgsV2', () => {
+      const original = { gasLimit: 400_000n, allowOutOfOrderExecution: true }
+      const encoded = encodeExtraArgs(original, ChainFamily.TON)
+      const decoded = decodeExtraArgs(encoded, ChainFamily.TON)
+      assert.deepEqual(decoded, { ...original, _tag: 'EVMExtraArgsV2' })
+    })
   })
 
   describe('encoding format differences', () => {
@@ -220,5 +289,15 @@ describe('parseExtraArgs', () => {
       // But different lengths
       assert.ok(evmEncoded.length > aptosEncoded.length)
     })
+
+    it('should produce different encodings for EVM vs TON', () => {
+      const args = { gasLimit: 300_000n, allowOutOfOrderExecution: false }
+      const evmEncoded = encodeExtraArgs(args, ChainFamily.EVM)
+      const tonEncoded = encodeExtraArgs(args, ChainFamily.TON)
+
+      assert.equal(evmEncoded.substring(0, 10), EVMExtraArgsV2Tag)
+      assert.equal(extractMagicTag(tonEncoded), EVMExtraArgsV2Tag)
+      assert.notEqual(evmEncoded, tonEncoded)
+    })
   })
 })

ccip-sdk/src/index.ts

@@ -44,8 +44,9 @@ import { AptosChain } from './aptos/index.ts'
 import { EVMChain } from './evm/index.ts'
 import { SolanaChain } from './solana/index.ts'
 import { SuiChain } from './sui/index.ts'
+import { TONChain } from './ton/index.ts'
 import { ChainFamily } from './types.ts'
-export { AptosChain, ChainFamily, EVMChain, SolanaChain, SuiChain }
+export { AptosChain, ChainFamily, EVMChain, SolanaChain, SuiChain, TONChain }
 // use `supportedChains` to override/register derived classes, if needed
 export { supportedChains } from './supported-chains.ts'
 // import `allSupportedChains` to get them all registered, in tree-shaken environments
@@ -54,4 +55,5 @@ export const allSupportedChains = {
   [ChainFamily.Solana]: SolanaChain,
   [ChainFamily.Aptos]: AptosChain,
   [ChainFamily.Sui]: SuiChain,
+  [ChainFamily.TON]: TONChain,
 }

ccip-sdk/src/selectors.ts

@@ -1335,6 +1335,29 @@ const selectors: Selectors = {
     family: 'sui',
   },
   // end:generate
+
+  // generate:
+  // fetch('https://github.com/smartcontractkit/chain-selectors/raw/main/selectors_ton.yml')
+  //   .then((res) => res.text())
+  //   .then((body) => require('yaml').parse(body, { intAsBigInt: true }).selectors)
+  //   .then((obj) => Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, { ...v, family: 'ton' }])))
+  //   .then((obj) => [...require('util').inspect(obj).split('\n').slice(1, -1), ','])
+  '-239': {
+    name: 'ton-mainnet',
+    selector: 16448340667252469081n,
+    family: 'ton',
+  },
+  '-3': {
+    name: 'ton-testnet',
+    selector: 1399300952838017768n,
+    family: 'ton',
+  },
+  '-217': {
+    name: 'ton-localnet',
+    selector: 13879075125137744094n,
+    family: 'ton',
+  },
+  // end:generate
 }
 
 export default selectors

ccip-sdk/src/solana/exec.ts

@@ -17,8 +17,7 @@ import { type ExecutionReport, type WithLogger, ChainFamily } from '../types.ts'
 import { IDL as CCIP_OFFRAMP_IDL } from './idl/1.6.0/CCIP_OFFRAMP.ts'
 import { encodeSolanaOffchainTokenData } from './offchain.ts'
 import type { CCIPMessage_V1_6_Solana, UnsignedSolanaTx } from './types.ts'
-import { getDataBytes, toLeArray } from '../utils.ts'
-import { bytesToBuffer } from './utils.ts'
+import { bytesToBuffer, getDataBytes, toLeArray } from '../utils.ts'
 
 type ExecAlt = {
   initialIxs: TransactionInstruction[]

ccip-sdk/src/solana/index.ts

@@ -61,6 +61,7 @@ import {
   ExecutionState,
 } from '../types.ts'
 import {
+  bytesToBuffer,
   createRateLimitedFetch,
   decodeAddress,
   decodeOnRampAddress,
@@ -83,7 +84,6 @@ import { fetchSolanaOffchainTokenData } from './offchain.ts'
 import { generateUnsignedCcipSend, getFee } from './send.ts'
 import { type CCIPMessage_V1_6_Solana, type UnsignedSolanaTx, isWallet } from './types.ts'
 import {
-  bytesToBuffer,
   getErrorFromLogs,
   hexDiscriminator,
   parseSolanaLogs,

ccip-sdk/src/solana/offchain.ts

@@ -4,11 +4,11 @@ import { hexlify } from 'ethers'
 
 import { getUsdcAttestation } from '../offchain.ts'
 import type { CCIPMessage, CCIPRequest, OffchainTokenData, WithLogger } from '../types.ts'
-import { networkInfo, util } from '../utils.ts'
+import { bytesToBuffer, networkInfo, util } from '../utils.ts'
 import { IDL as BASE_TOKEN_POOL } from './idl/1.6.0/BASE_TOKEN_POOL.ts'
 import { IDL as CCTP_TOKEN_POOL } from './idl/1.6.0/CCIP_CCTP_TOKEN_POOL.ts'
 import type { SolanaLog, SolanaTransaction } from './index.ts'
-import { bytesToBuffer, hexDiscriminator } from './utils.ts'
+import { hexDiscriminator } from './utils.ts'
 
 interface CcipCctpMessageSentEvent {
   originalSender: PublicKey

ccip-sdk/src/solana/send.ts

@@ -19,10 +19,10 @@ import { zeroPadValue } from 'ethers'
 
 import { SolanaChain } from './index.ts'
 import { type AnyMessage, type WithLogger, ChainFamily } from '../types.ts'
-import { toLeArray, util } from '../utils.ts'
+import { bytesToBuffer, toLeArray, util } from '../utils.ts'
 import { IDL as CCIP_ROUTER_IDL } from './idl/1.6.0/CCIP_ROUTER.ts'
 import type { UnsignedSolanaTx } from './types.ts'
-import { bytesToBuffer, simulationProvider } from './utils.ts'
+import { simulationProvider } from './utils.ts'
 
 function anyToSvmMessage(message: AnyMessage): IdlTypes<typeof CCIP_ROUTER_IDL>['SVM2AnyMessage'] {
   const feeTokenPubkey = message.feeToken ? new PublicKey(message.feeToken) : PublicKey.default

ccip-sdk/src/solana/utils.ts

@@ -1,5 +1,3 @@
-import { Buffer } from 'buffer'
-
 import { eventDiscriminator } from '@coral-xyz/anchor'
 import {
   type AddressLookupTableAccount,
@@ -14,7 +12,7 @@ import {
   TransactionMessage,
   VersionedTransaction,
 } from '@solana/web3.js'
-import { type BytesLike, dataLength, dataSlice, hexlify } from 'ethers'
+import { dataLength, dataSlice, hexlify } from 'ethers'
 
 import type { Log_, WithLogger } from '../types.ts'
 import { getDataBytes, sleep } from '../utils.ts'
@@ -29,15 +27,6 @@ export function hexDiscriminator(eventName: string): string {
   return hexlify(eventDiscriminator(eventName))
 }
 
-/**
- * Converts bytes to a Node.js Buffer.
- * @param bytes - Bytes to convert.
- * @returns Node.js Buffer.
- */
-export function bytesToBuffer(bytes: BytesLike): Buffer {
-  return Buffer.from(getDataBytes(bytes).buffer)
-}
-
 /**
  * Waits for a Solana transaction to reach finalized status.
  * @param connection - Solana connection instance.