@meshconnect/uwc-ton-connector 0.2.2 → 0.4.0

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/namespaced-storage.ts

@@ -1,9 +1,4 @@
-/** Mirrors @tonconnect/sdk IStorage — avoids leaking SDK types in published .d.ts. */
-export interface TonConnectStorage {
-  setItem(key: string, value: string): Promise<void>
-  getItem(key: string): Promise<string | null>
-  removeItem(key: string): Promise<void>
-}
+import type { IStorage } from '@tonconnect/sdk'
 
 /**
  * Prefixed localStorage wrapper required by @tonconnect/sdk.
@@ -11,7 +6,7 @@ export interface TonConnectStorage {
  * Keys are prefixed per wallet (e.g. "tonkeeper:session") to avoid collisions.
  * Falls back to in-memory Map when localStorage is blocked (Safari ITP in iframes).
  */
-export class NamespacedStorage implements TonConnectStorage {
+export class NamespacedStorage implements IStorage {
   private memoryFallback = new Map<string, string>()
 
   constructor(private prefix: string) {}