@gasfree-kit/ton-gasless 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,152 @@
+# @gasfree-kit/ton-gasless
+
+Gasless USDT transfers on TON through a sponsored relay.
+
+With this package, the user only needs USDT. The relay pays the TON gas and charges a small fee back in USDT.
+
+## What This Package Does
+
+- creates a WDK-backed TON wallet
+- quotes the relay fee in USDT
+- checks that balance covers transfer amount plus fee
+- submits the gasless transfer
+- returns a transfer context you can log or persist
+
+## Transfer Diagram
+
+```mermaid
+flowchart LR
+  App["Your app"] --> SDK["@gasfree-kit/ton-gasless"]
+  SDK --> Wallet["WDK TON wallet"]
+  SDK --> Quote["Relay fee quote"]
+  Quote --> Relay["Sponsored relay"]
+  Relay --> TON["TON blockchain"]
+  Relay --> Fee["USDT commission"]
+```
+
+## Installation
+
+```bash
+npm install @gasfree-kit/ton-gasless
+```
+
+Peer dependencies:
+
+```bash
+npm install @tetherto/wdk-wallet-ton-gasless tonweb
+```
+
+## Configuration
+
+```ts
+import type { TonGaslessClientConfig } from '@gasfree-kit/ton-gasless';
+
+const config: TonGaslessClientConfig = {
+  tonCenterUrl: 'https://toncenter.com/api/v2',
+  tonCenterApiKey: 'your-toncenter-api-key',
+  tonApiUrl: 'https://tonapi.io',
+  tonApiSecretKey: 'your-tonapi-secret-key',
+  // Optional:
+  // transferMaxFee: 1_000_000,
+  // usdtAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
+};
+```
+
+### Config fields
+
+| Field             | Purpose                                            |
+| ----------------- | -------------------------------------------------- |
+| `tonCenterUrl`    | TON Center endpoint used by the wallet client      |
+| `tonCenterApiKey` | TON Center API key                                 |
+| `tonApiUrl`       | TON API endpoint                                   |
+| `tonApiSecretKey` | TON API secret key                                 |
+| `transferMaxFee`  | Maximum fee limit in base units, capped by the SDK |
+| `usdtAddress`     | Optional override for the TON USDT root            |
+
+## Quick Start
+
+### 1. Set up a wallet
+
+```ts
+import { setupTonGaslessWallet } from '@gasfree-kit/ton-gasless';
+
+const seedPhrase = 'your twelve word seed phrase here ...';
+const { wallet, account, address } = await setupTonGaslessWallet(seedPhrase, config);
+
+console.log(address);
+```
+
+If you need a specific derivation path:
+
+```ts
+const walletResult = await setupTonGaslessWallet(seedPhrase, config, "0'/0/0");
+```
+
+### 2. Check USDT balance
+
+```ts
+import { TonTransfer } from '@gasfree-kit/ton-gasless';
+
+const balance = await TonTransfer.checkBalance(seedPhrase, config);
+
+console.log(balance.data.usdBalance);
+console.log(balance.data.tokenBalance);
+```
+
+### 3. Estimate the fee
+
+```ts
+const estimate = await TonTransfer.getTransactionEstimateFee(
+  seedPhrase,
+  config,
+  '10.00',
+  'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
+);
+
+console.log(estimate.data.fee);
+```
+
+### 4. Execute the gasless transfer
+
+```ts
+const result = await TonTransfer.transferUSDT(
+  seedPhrase,
+  config,
+  '50.00',
+  'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
+);
+
+console.log(result.data.transactionHash);
+console.log(result.data.fee);
+```
+
+## How The Flow Behaves
+
+1. The SDK validates the recipient address.
+2. The SDK asks the relay path for a fee quote.
+3. The SDK checks that the wallet balance can cover `amount + fee`.
+4. The transfer is submitted.
+5. The relay pays TON gas and deducts the fee in USDT.
+
+## Main Exports
+
+| Export                   | What it does                                               |
+| ------------------------ | ---------------------------------------------------------- |
+| `setupTonGaslessWallet`  | Creates the WDK-backed TON wallet and resolves the address |
+| `TonTransfer`            | Checks balances, estimates fees, and sends transfers       |
+| `getTonGaslessConfig`    | Expands and validates the runtime config                   |
+| `tonUsdtTokenRoot`       | Built-in TON USDT root address                             |
+| `usdtTonBaseUnits`       | Converts human-readable USDT to base units                 |
+| `fromTonBaseUnitsToUsdt` | Converts base units back to readable USDT                  |
+| `getTonUsdtValue`        | Utility helper for TON to USDT conversions                 |
+
+## Safety Notes
+
+- `transferMaxFee` is capped by the SDK to prevent extreme fee deductions
+- invalid TON addresses are rejected before sending
+- self-transfers are blocked
+- the user must have enough USDT for both transfer amount and fee
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -37,7 +37,7 @@ declare function setupTonGaslessWallet(seedPhrase: string, config: TonGaslessCli
     address: string;
 }>;
 
-declare class TonGaslessTetherTransfer {
+declare class TonTransfer {
     /**
      * Get transaction fee estimate for a gasless USDT transfer on TON.
      * The gasless commission is returned in USDT (paymaster token units).
@@ -56,7 +56,7 @@ declare class TonGaslessTetherTransfer {
         message: string;
         success: boolean;
         data: {
-            nativeBalance: number;
+            tokenBalance: string;
             decimals: number;
             usdBalance: string;
         };
@@ -98,4 +98,4 @@ declare function fromTonBaseUnitsToUsdt(amount: bigint, dec?: number): string;
  */
 declare function getTonUsdtValue(amountInBaseUnits: bigint, exchangeRate: number): number;
 
-export { type TonGaslessClientConfig, type TonGaslessNetworkConfig, TonGaslessTetherTransfer, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };
+export { type TonGaslessClientConfig, type TonGaslessNetworkConfig, TonTransfer, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };

package/dist/index.d.ts

@@ -37,7 +37,7 @@ declare function setupTonGaslessWallet(seedPhrase: string, config: TonGaslessCli
     address: string;
 }>;
 
-declare class TonGaslessTetherTransfer {
+declare class TonTransfer {
     /**
      * Get transaction fee estimate for a gasless USDT transfer on TON.
      * The gasless commission is returned in USDT (paymaster token units).
@@ -56,7 +56,7 @@ declare class TonGaslessTetherTransfer {
         message: string;
         success: boolean;
         data: {
-            nativeBalance: number;
+            tokenBalance: string;
             decimals: number;
             usdBalance: string;
         };
@@ -98,4 +98,4 @@ declare function fromTonBaseUnitsToUsdt(amount: bigint, dec?: number): string;
  */
 declare function getTonUsdtValue(amountInBaseUnits: bigint, exchangeRate: number): number;
 
-export { type TonGaslessClientConfig, type TonGaslessNetworkConfig, TonGaslessTetherTransfer, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };
+export { type TonGaslessClientConfig, type TonGaslessNetworkConfig, TonTransfer, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };

package/dist/index.js

@@ -30,7 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  TonGaslessTetherTransfer: () => TonGaslessTetherTransfer,
+  TonTransfer: () => TonTransfer,
   fromTonBaseUnitsToUsdt: () => fromTonBaseUnitsToUsdt,
   getTonGaslessConfig: () => getTonGaslessConfig,
   getTonUsdtValue: () => getTonUsdtValue,
@@ -112,7 +112,7 @@ function getTonUsdtValue(amountInBaseUnits, exchangeRate) {
 }
 
 // src/tonGaslessTetherTransfer.ts
-var TonGaslessTetherTransfer = class {
+var TonTransfer = class {
   /**
    * Get transaction fee estimate for a gasless USDT transfer on TON.
    * The gasless commission is returned in USDT (paymaster token units).
@@ -150,7 +150,7 @@ var TonGaslessTetherTransfer = class {
         message: "TON balances retrieved successfully",
         success: true,
         data: {
-          nativeBalance: Number(balance),
+          tokenBalance: balance.toString(),
           decimals: 6,
           usdBalance: String(usdBalance)
         }
@@ -230,7 +230,7 @@ var TonGaslessTetherTransfer = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  TonGaslessTetherTransfer,
+  TonTransfer,
   fromTonBaseUnitsToUsdt,
   getTonGaslessConfig,
   getTonUsdtValue,

package/dist/index.mjs

@@ -74,7 +74,7 @@ function getTonUsdtValue(amountInBaseUnits, exchangeRate) {
 }
 
 // src/tonGaslessTetherTransfer.ts
-var TonGaslessTetherTransfer = class {
+var TonTransfer = class {
   /**
    * Get transaction fee estimate for a gasless USDT transfer on TON.
    * The gasless commission is returned in USDT (paymaster token units).
@@ -112,7 +112,7 @@ var TonGaslessTetherTransfer = class {
         message: "TON balances retrieved successfully",
         success: true,
         data: {
-          nativeBalance: Number(balance),
+          tokenBalance: balance.toString(),
           decimals: 6,
           usdBalance: String(usdBalance)
         }
@@ -191,7 +191,7 @@ var TonGaslessTetherTransfer = class {
   }
 };
 export {
-  TonGaslessTetherTransfer,
+  TonTransfer,
   fromTonBaseUnitsToUsdt,
   getTonGaslessConfig,
   getTonUsdtValue,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasfree-kit/ton-gasless",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Gasless USDT transfers on TON via sponsored relay",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -13,10 +13,11 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
-    "@gasfree-kit/core": "0.1.0"
+    "@gasfree-kit/core": "0.1.1"
   },
   "peerDependencies": {
     "@tetherto/wdk-wallet-ton-gasless": "^1.0.0-beta.4",