@meshconnect/uwc-ton-connector 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { NamespacedStorage } from './namespaced-storage';
 export { isValidBase64 } from './validation';
 export { buildTonTransactionRequest, buildSignDataPayload, executeSignData, unwrapBoc, bocToHash, toFriendlyAddress } from './ton-transaction-utils';
+export { buildJettonTransferPayload, buildTonNativeRequestFromJettonTransfer } from './jetton-transfer';
 export { TonConnectConnector } from './ton-connect-connector';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,SAAS,EACT,iBAAiB,EAClB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,SAAS,EACT,iBAAiB,EAClB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,0BAA0B,EAC1B,uCAAuC,EACxC,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export { NamespacedStorage } from './namespaced-storage';
 export { isValidBase64 } from './validation';
 export { buildTonTransactionRequest, buildSignDataPayload, executeSignData, unwrapBoc, bocToHash, toFriendlyAddress } from './ton-transaction-utils';
+export { buildJettonTransferPayload, buildTonNativeRequestFromJettonTransfer } from './jetton-transfer';
 export { TonConnectConnector } from './ton-connect-connector';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,SAAS,EACT,iBAAiB,EAClB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,SAAS,EACT,iBAAiB,EAClB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,0BAA0B,EAC1B,uCAAuC,EACxC,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/jetton-transfer.d.ts

@@ -0,0 +1,27 @@
+import type { TonJettonTransferParams, TonNativeTransferRequest } from '@meshconnect/uwc-types';
+/**
+ * Build the TEP-74 Jetton transfer message body as a base64 BOC.
+ *
+ * Unlike EVM/Solana/TRON where wallets know how to encode token transfers,
+ * TON Connect wallets only accept raw messages with an optional payload.
+ * We must encode the Jetton transfer Cell (opcode, amount, destination, etc.)
+ * ourselves and pass it as the payload field.
+ *
+ * @param params - Logical jetton transfer parameters (destination, amount in base units, etc.)
+ * @returns Base64-encoded BOC of the transfer cell (use as payload in TonNativeTransferRequest)
+ */
+export declare function buildJettonTransferPayload(params: TonJettonTransferParams): Promise<string>;
+/**
+ * Build a TonNativeTransferRequest for a Jetton transfer.
+ *
+ * Wraps the encoded Cell into a standard TonNativeTransferRequest. The field mapping
+ * is intentionally different from a native TON transfer:
+ * - `to` = sender's Jetton wallet contract (not the recipient — the recipient is inside the Cell)
+ * - `amount` = gas in nanotons (not the token amount — that's also inside the Cell)
+ * - `payload` = the TEP-74 Cell built by buildJettonTransferPayload
+ *
+ * The caller must resolve the sender's Jetton wallet address (e.g. via get_wallet_address
+ * on the Jetton master, or computed locally from the wallet code + owner address).
+ */
+export declare function buildTonNativeRequestFromJettonTransfer(params: TonJettonTransferParams, senderJettonWalletAddress: string, fromAddress: string, gasNanotons: string): Promise<TonNativeTransferRequest>;
+//# sourceMappingURL=jetton-transfer.d.ts.map

package/dist/jetton-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jetton-transfer.d.ts","sourceRoot":"","sources":["../src/jetton-transfer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,wBAAwB,CAAA;AAgB/B;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,MAAM,CAAC,CA8DjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uCAAuC,CAC3D,MAAM,EAAE,uBAAuB,EAC/B,yBAAyB,EAAE,MAAM,EACjC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,wBAAwB,CAAC,CAQnC"}

package/dist/jetton-transfer.js

@@ -0,0 +1,103 @@
+/**
+ * TEP-74 Jetton transfer op code. Identifies the message as a token transfer.
+ * This is a protocol-level constant defined in the standard — all Jetton contracts
+ * use this same value, so it's safe to hardcode.
+ * @see https://github.com/ton-blockchain/TEPs/blob/master/text/0074-jettons-standard.md
+ */
+const JETTON_TRANSFER_OP = 0x0f8a7ea5;
+/** TEP-74 forward_payload comment op code (0 = text comment). */
+const FORWARD_PAYLOAD_OP_COMMENT = 0;
+/** Max value for a 64-bit unsigned integer (TEP-74 query_id). */
+const MAX_UINT64 = 18446744073709551615n;
+/**
+ * Build the TEP-74 Jetton transfer message body as a base64 BOC.
+ *
+ * Unlike EVM/Solana/TRON where wallets know how to encode token transfers,
+ * TON Connect wallets only accept raw messages with an optional payload.
+ * We must encode the Jetton transfer Cell (opcode, amount, destination, etc.)
+ * ourselves and pass it as the payload field.
+ *
+ * @param params - Logical jetton transfer parameters (destination, amount in base units, etc.)
+ * @returns Base64-encoded BOC of the transfer cell (use as payload in TonNativeTransferRequest)
+ */
+export async function buildJettonTransferPayload(params) {
+    const { beginCell, Address } = await import('@ton/core');
+    let queryId;
+    try {
+        queryId = BigInt(params.queryId ?? '0');
+    }
+    catch {
+        throw new Error('queryId must be a valid integer string');
+    }
+    if (queryId < 0n || queryId > MAX_UINT64) {
+        throw new Error(`queryId must be a uint64 (0 to ${MAX_UINT64})`);
+    }
+    let amount;
+    try {
+        amount = BigInt(params.amount);
+    }
+    catch {
+        throw new Error('amount must be a valid integer string');
+    }
+    if (amount < 0n) {
+        throw new Error('Jetton transfer amount must be non-negative');
+    }
+    const destination = Address.parse(params.destination);
+    const responseDestination = Address.parse(params.responseDestination);
+    let forwardTonAmount;
+    try {
+        forwardTonAmount = BigInt(params.forwardTonAmount ?? '0');
+    }
+    catch {
+        throw new Error('forwardTonAmount must be a valid integer string');
+    }
+    if (forwardTonAmount < 0n) {
+        throw new Error('forwardTonAmount must be non-negative');
+    }
+    const hasForwardComment = params.forwardComment != null &&
+        params.forwardComment.length > 0 &&
+        forwardTonAmount > 0n;
+    const body = beginCell()
+        .storeUint(JETTON_TRANSFER_OP, 32)
+        .storeUint(queryId, 64)
+        .storeCoins(amount)
+        .storeAddress(destination)
+        .storeAddress(responseDestination)
+        .storeBit(0) // no custom_payload
+        .storeCoins(forwardTonAmount);
+    if (hasForwardComment) {
+        const forwardPayload = beginCell()
+            .storeUint(FORWARD_PAYLOAD_OP_COMMENT, 32)
+            .storeStringTail(params.forwardComment)
+            .endCell();
+        body.storeBit(1);
+        body.storeRef(forwardPayload);
+    }
+    else {
+        body.storeBit(0);
+    }
+    const cell = body.endCell();
+    return cell.toBoc().toString('base64');
+}
+/**
+ * Build a TonNativeTransferRequest for a Jetton transfer.
+ *
+ * Wraps the encoded Cell into a standard TonNativeTransferRequest. The field mapping
+ * is intentionally different from a native TON transfer:
+ * - `to` = sender's Jetton wallet contract (not the recipient — the recipient is inside the Cell)
+ * - `amount` = gas in nanotons (not the token amount — that's also inside the Cell)
+ * - `payload` = the TEP-74 Cell built by buildJettonTransferPayload
+ *
+ * The caller must resolve the sender's Jetton wallet address (e.g. via get_wallet_address
+ * on the Jetton master, or computed locally from the wallet code + owner address).
+ */
+export async function buildTonNativeRequestFromJettonTransfer(params, senderJettonWalletAddress, fromAddress, gasNanotons) {
+    const payload = await buildJettonTransferPayload(params);
+    return {
+        to: senderJettonWalletAddress,
+        amount: gasNanotons,
+        from: fromAddress,
+        payload
+    };
+}
+//# sourceMappingURL=jetton-transfer.js.map

package/dist/jetton-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jetton-transfer.js","sourceRoot":"","sources":["../src/jetton-transfer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshconnect/uwc-ton-connector",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TON Connect connector for Universal Wallet Connector — mobile QR/URI wallet connections",
   "type": "module",
   "main": "dist/index.js",
@@ -18,8 +18,8 @@
   "dependencies": {
     "@ton/core": "^0.63.1",
     "@tonconnect/sdk": "^3.0.5",
-    "@meshconnect/uwc-constants": "0.5.3",
-    "@meshconnect/uwc-types": "0.9.0"
+    "@meshconnect/uwc-constants": "0.5.4",
+    "@meshconnect/uwc-types": "0.10.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/index.ts

@@ -8,4 +8,8 @@ export {
   bocToHash,
   toFriendlyAddress
 } from './ton-transaction-utils'
+export {
+  buildJettonTransferPayload,
+  buildTonNativeRequestFromJettonTransfer
+} from './jetton-transfer'
 export { TonConnectConnector } from './ton-connect-connector'

package/src/jetton-transfer.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect } from 'vitest'
+import { Cell } from '@ton/core'
+import {
+  buildJettonTransferPayload,
+  buildTonNativeRequestFromJettonTransfer
+} from './jetton-transfer'
+import type { TonJettonTransferParams } from '@meshconnect/uwc-types'
+
+// Any valid TON address works for testing Cell encoding
+const TEST_ADDRESS = 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs'
+const DEST = TEST_ADDRESS
+const RESPONSE_DEST = TEST_ADDRESS
+
+describe('buildJettonTransferPayload', () => {
+  it('returns base64 BOC with correct op code and amount', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '1000000',
+      responseDestination: RESPONSE_DEST
+    }
+    const payload = await buildJettonTransferPayload(params)
+    expect(typeof payload).toBe('string')
+    expect(payload.length).toBeGreaterThan(0)
+    const cell = Cell.fromBase64(payload)
+    const slice = cell.beginParse()
+    const op = slice.loadUint(32)
+    expect(op).toBe(0x0f8a7ea5)
+    const queryId = slice.loadUintBig(64)
+    expect(queryId).toBe(0n)
+    const amount = slice.loadCoins()
+    expect(amount).toBe(1000000n)
+  })
+
+  it('includes forward comment when forwardTonAmount > 0', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '500000',
+      responseDestination: RESPONSE_DEST,
+      forwardTonAmount: '20000000',
+      forwardComment: 'for coffee'
+    }
+    const payload = await buildJettonTransferPayload(params)
+    const cell = Cell.fromBase64(payload)
+    const slice = cell.beginParse()
+    slice.loadUint(32) // op
+    slice.loadUintBig(64) // query_id
+    slice.loadCoins() // amount
+    slice.loadAddress() // destination
+    slice.loadAddress() // response_destination
+    slice.loadBit() // custom_payload
+    const forwardTon = slice.loadCoins()
+    expect(forwardTon).toBe(20000000n)
+    const hasForwardRef = slice.loadBit()
+    expect(hasForwardRef).toBe(true)
+    const ref = slice.loadRef()
+    const refSlice = ref.beginParse()
+    const commentOp = refSlice.loadUint(32)
+    expect(commentOp).toBe(0)
+    const comment = refSlice.loadStringTail()
+    expect(comment).toBe('for coffee')
+  })
+
+  it('uses custom queryId when provided', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '1',
+      responseDestination: RESPONSE_DEST,
+      queryId: '12345'
+    }
+    const payload = await buildJettonTransferPayload(params)
+    const cell = Cell.fromBase64(payload)
+    const slice = cell.beginParse()
+    slice.loadUint(32)
+    const queryId = slice.loadUintBig(64)
+    expect(queryId).toBe(12345n)
+  })
+
+  it('throws when forwardTonAmount is negative', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '1000000',
+      responseDestination: RESPONSE_DEST,
+      forwardTonAmount: '-1'
+    }
+    await expect(buildJettonTransferPayload(params)).rejects.toThrow(
+      'forwardTonAmount must be non-negative'
+    )
+  })
+
+  it('throws when queryId exceeds uint64 max', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '1000000',
+      responseDestination: RESPONSE_DEST,
+      queryId: '18446744073709551616' // 2^64, one above max
+    }
+    await expect(buildJettonTransferPayload(params)).rejects.toThrow(
+      'queryId must be a uint64'
+    )
+  })
+
+  it('throws when queryId is negative', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '1000000',
+      responseDestination: RESPONSE_DEST,
+      queryId: '-1'
+    }
+    await expect(buildJettonTransferPayload(params)).rejects.toThrow(
+      'queryId must be a uint64'
+    )
+  })
+
+  it('accepts zero amount', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '0',
+      responseDestination: RESPONSE_DEST
+    }
+    const payload = await buildJettonTransferPayload(params)
+    const cell = Cell.fromBase64(payload)
+    const slice = cell.beginParse()
+    slice.loadUint(32) // op
+    slice.loadUintBig(64) // queryId
+    const amount = slice.loadCoins()
+    expect(amount).toBe(0n)
+  })
+
+  it('throws when amount is not a valid integer string', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: 'abc',
+      responseDestination: RESPONSE_DEST
+    }
+    await expect(buildJettonTransferPayload(params)).rejects.toThrow(
+      'amount must be a valid integer string'
+    )
+  })
+
+  it('throws when queryId is not a valid integer string', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '1000000',
+      responseDestination: RESPONSE_DEST,
+      queryId: 'not-a-number'
+    }
+    await expect(buildJettonTransferPayload(params)).rejects.toThrow(
+      'queryId must be a valid integer string'
+    )
+  })
+
+  it('throws when forwardTonAmount is not a valid integer string', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '1000000',
+      responseDestination: RESPONSE_DEST,
+      forwardTonAmount: 'xyz'
+    }
+    await expect(buildJettonTransferPayload(params)).rejects.toThrow(
+      'forwardTonAmount must be a valid integer string'
+    )
+  })
+
+  it('throws when amount is negative', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '-1',
+      responseDestination: RESPONSE_DEST
+    }
+    await expect(buildJettonTransferPayload(params)).rejects.toThrow(
+      'Jetton transfer amount must be non-negative'
+    )
+  })
+})
+
+describe('buildTonNativeRequestFromJettonTransfer', () => {
+  it('builds request with to = sender jetton wallet and payload from params', async () => {
+    const params: TonJettonTransferParams = {
+      destination: DEST,
+      amount: '1000000',
+      responseDestination: RESPONSE_DEST
+    }
+    const senderJettonWallet = TEST_ADDRESS
+    const from = TEST_ADDRESS
+    const gas = '100000000'
+
+    const request = await buildTonNativeRequestFromJettonTransfer(
+      params,
+      senderJettonWallet,
+      from,
+      gas
+    )
+
+    expect(request.to).toBe(senderJettonWallet)
+    expect(request.amount).toBe(gas)
+    expect(request.from).toBe(from)
+    expect(request.payload).toBe(await buildJettonTransferPayload(params))
+  })
+})

package/src/jetton-transfer.ts

@@ -0,0 +1,122 @@
+import type {
+  TonJettonTransferParams,
+  TonNativeTransferRequest
+} from '@meshconnect/uwc-types'
+
+/**
+ * TEP-74 Jetton transfer op code. Identifies the message as a token transfer.
+ * This is a protocol-level constant defined in the standard — all Jetton contracts
+ * use this same value, so it's safe to hardcode.
+ * @see https://github.com/ton-blockchain/TEPs/blob/master/text/0074-jettons-standard.md
+ */
+const JETTON_TRANSFER_OP = 0x0f8a7ea5
+
+/** TEP-74 forward_payload comment op code (0 = text comment). */
+const FORWARD_PAYLOAD_OP_COMMENT = 0
+
+/** Max value for a 64-bit unsigned integer (TEP-74 query_id). */
+const MAX_UINT64 = 18446744073709551615n
+
+/**
+ * Build the TEP-74 Jetton transfer message body as a base64 BOC.
+ *
+ * Unlike EVM/Solana/TRON where wallets know how to encode token transfers,
+ * TON Connect wallets only accept raw messages with an optional payload.
+ * We must encode the Jetton transfer Cell (opcode, amount, destination, etc.)
+ * ourselves and pass it as the payload field.
+ *
+ * @param params - Logical jetton transfer parameters (destination, amount in base units, etc.)
+ * @returns Base64-encoded BOC of the transfer cell (use as payload in TonNativeTransferRequest)
+ */
+export async function buildJettonTransferPayload(
+  params: TonJettonTransferParams
+): Promise<string> {
+  const { beginCell, Address } = await import('@ton/core')
+
+  let queryId: bigint
+  try {
+    queryId = BigInt(params.queryId ?? '0')
+  } catch {
+    throw new Error('queryId must be a valid integer string')
+  }
+  if (queryId < 0n || queryId > MAX_UINT64) {
+    throw new Error(`queryId must be a uint64 (0 to ${MAX_UINT64})`)
+  }
+
+  let amount: bigint
+  try {
+    amount = BigInt(params.amount)
+  } catch {
+    throw new Error('amount must be a valid integer string')
+  }
+  if (amount < 0n) {
+    throw new Error('Jetton transfer amount must be non-negative')
+  }
+
+  const destination = Address.parse(params.destination)
+  const responseDestination = Address.parse(params.responseDestination)
+
+  let forwardTonAmount: bigint
+  try {
+    forwardTonAmount = BigInt(params.forwardTonAmount ?? '0')
+  } catch {
+    throw new Error('forwardTonAmount must be a valid integer string')
+  }
+  if (forwardTonAmount < 0n) {
+    throw new Error('forwardTonAmount must be non-negative')
+  }
+  const hasForwardComment =
+    params.forwardComment != null &&
+    params.forwardComment.length > 0 &&
+    forwardTonAmount > 0n
+
+  const body = beginCell()
+    .storeUint(JETTON_TRANSFER_OP, 32)
+    .storeUint(queryId, 64)
+    .storeCoins(amount)
+    .storeAddress(destination)
+    .storeAddress(responseDestination)
+    .storeBit(0) // no custom_payload
+    .storeCoins(forwardTonAmount)
+
+  if (hasForwardComment) {
+    const forwardPayload = beginCell()
+      .storeUint(FORWARD_PAYLOAD_OP_COMMENT, 32)
+      .storeStringTail(params.forwardComment as string)
+      .endCell()
+    body.storeBit(1)
+    body.storeRef(forwardPayload)
+  } else {
+    body.storeBit(0)
+  }
+
+  const cell = body.endCell()
+  return cell.toBoc().toString('base64')
+}
+
+/**
+ * Build a TonNativeTransferRequest for a Jetton transfer.
+ *
+ * Wraps the encoded Cell into a standard TonNativeTransferRequest. The field mapping
+ * is intentionally different from a native TON transfer:
+ * - `to` = sender's Jetton wallet contract (not the recipient — the recipient is inside the Cell)
+ * - `amount` = gas in nanotons (not the token amount — that's also inside the Cell)
+ * - `payload` = the TEP-74 Cell built by buildJettonTransferPayload
+ *
+ * The caller must resolve the sender's Jetton wallet address (e.g. via get_wallet_address
+ * on the Jetton master, or computed locally from the wallet code + owner address).
+ */
+export async function buildTonNativeRequestFromJettonTransfer(
+  params: TonJettonTransferParams,
+  senderJettonWalletAddress: string,
+  fromAddress: string,
+  gasNanotons: string
+): Promise<TonNativeTransferRequest> {
+  const payload = await buildJettonTransferPayload(params)
+  return {
+    to: senderJettonWalletAddress,
+    amount: gasNanotons,
+    from: fromAddress,
+    payload
+  }
+}

package/src/ton-connect-connector.test.ts

@@ -501,6 +501,42 @@ describe('TonConnectConnector', () => {
       expect(txArg.from).toBe('0:sender_raw')
     })
 
+    it('sends a pre-built Jetton transfer (payload in TonNativeTransferRequest)', async () => {
+      simulateSuccessfulConnect()
+      await connector.connect(TON_NETWORK, PROVIDER)
+
+      getLastSdkInstance()!.account = {
+        address: '0:abcdef1234567890',
+        chain: '-239'
+      }
+      mockSendTransaction.mockResolvedValue({ boc: 'te6cckJettonBoc...' })
+
+      // Simulate what the app layer does: buildTonNativeRequestFromJettonTransfer
+      // wraps a Jetton Cell into a TonNativeTransferRequest where:
+      //   to = sender's Jetton wallet (NOT the recipient)
+      //   amount = gas nanotons (NOT the token amount)
+      //   payload = base64 BOC of the TEP-74 Cell
+      // Use a real base64 string to pass payload validation
+      const fakeJettonPayload = btoa('jetton-cell-boc')
+
+      const result = await connector.sendTransaction!({
+        to: 'EQBsenderJettonWallet',
+        amount: '100000000', // 0.1 TON gas
+        from: 'UQBsender',
+        payload: fakeJettonPayload
+      })
+
+      expect(mockSendTransaction).toHaveBeenCalled()
+      const txArg = mockSendTransaction.mock.calls[0][0]
+      // The SDK message should target the Jetton wallet, not a recipient
+      expect(txArg.messages[0].address).toBe('EQBsenderJettonWallet')
+      // Amount is gas, not token amount
+      expect(txArg.messages[0].amount).toBe('100000000')
+      // Payload (Jetton Cell BOC) is passed through
+      expect(txArg.messages[0].payload).toBe(fakeJettonPayload)
+      expect(result).toBe('hash_of_te6cckJettonBoc...')
+    })
+
     it('wraps UserRejectsError with clear message', async () => {
       simulateSuccessfulConnect()
       await connector.connect(TON_NETWORK, PROVIDER)