@gasfree-kit/ton-gasless 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +192 -152
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,152 +1,192 @@
1
- # @gasfree-kit/ton-gasless
2
-
3
- Gasless USDT transfers on TON through a sponsored relay.
4
-
5
- With this package, the user only needs USDT. The relay pays the TON gas and charges a small fee back in USDT.
6
-
7
- ## What This Package Does
8
-
9
- - creates a WDK-backed TON wallet
10
- - quotes the relay fee in USDT
11
- - checks that balance covers transfer amount plus fee
12
- - submits the gasless transfer
13
- - returns a transfer context you can log or persist
14
-
15
- ## Transfer Diagram
16
-
17
- ```mermaid
18
- flowchart LR
19
- App["Your app"] --> SDK["@gasfree-kit/ton-gasless"]
20
- SDK --> Wallet["WDK TON wallet"]
21
- SDK --> Quote["Relay fee quote"]
22
- Quote --> Relay["Sponsored relay"]
23
- Relay --> TON["TON blockchain"]
24
- Relay --> Fee["USDT commission"]
25
- ```
26
-
27
- ## Installation
28
-
29
- ```bash
30
- npm install @gasfree-kit/ton-gasless
31
- ```
32
-
33
- Peer dependencies:
34
-
35
- ```bash
36
- npm install @tetherto/wdk-wallet-ton-gasless tonweb
37
- ```
38
-
39
- ## Configuration
40
-
41
- ```ts
42
- import type { TonGaslessClientConfig } from '@gasfree-kit/ton-gasless';
43
-
44
- const config: TonGaslessClientConfig = {
45
- tonCenterUrl: 'https://toncenter.com/api/v2',
46
- tonCenterApiKey: 'your-toncenter-api-key',
47
- tonApiUrl: 'https://tonapi.io',
48
- tonApiSecretKey: 'your-tonapi-secret-key',
49
- // Optional:
50
- // transferMaxFee: 1_000_000,
51
- // usdtAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
52
- };
53
- ```
54
-
55
- ### Config fields
56
-
57
- | Field | Purpose |
58
- | ----------------- | -------------------------------------------------- |
59
- | `tonCenterUrl` | TON Center endpoint used by the wallet client |
60
- | `tonCenterApiKey` | TON Center API key |
61
- | `tonApiUrl` | TON API endpoint |
62
- | `tonApiSecretKey` | TON API secret key |
63
- | `transferMaxFee` | Maximum fee limit in base units, capped by the SDK |
64
- | `usdtAddress` | Optional override for the TON USDT root |
65
-
66
- ## Quick Start
67
-
68
- ### 1. Set up a wallet
69
-
70
- ```ts
71
- import { setupTonGaslessWallet } from '@gasfree-kit/ton-gasless';
72
-
73
- const seedPhrase = 'your twelve word seed phrase here ...';
74
- const { wallet, account, address } = await setupTonGaslessWallet(seedPhrase, config);
75
-
76
- console.log(address);
77
- ```
78
-
79
- If you need a specific derivation path:
80
-
81
- ```ts
82
- const walletResult = await setupTonGaslessWallet(seedPhrase, config, "0'/0/0");
83
- ```
84
-
85
- ### 2. Check USDT balance
86
-
87
- ```ts
88
- import { TonTransfer } from '@gasfree-kit/ton-gasless';
89
-
90
- const balance = await TonTransfer.checkBalance(seedPhrase, config);
91
-
92
- console.log(balance.data.usdBalance);
93
- console.log(balance.data.tokenBalance);
94
- ```
95
-
96
- ### 3. Estimate the fee
97
-
98
- ```ts
99
- const estimate = await TonTransfer.getTransactionEstimateFee(
100
- seedPhrase,
101
- config,
102
- '10.00',
103
- 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
104
- );
105
-
106
- console.log(estimate.data.fee);
107
- ```
108
-
109
- ### 4. Execute the gasless transfer
110
-
111
- ```ts
112
- const result = await TonTransfer.transferUSDT(
113
- seedPhrase,
114
- config,
115
- '50.00',
116
- 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
117
- );
118
-
119
- console.log(result.data.transactionHash);
120
- console.log(result.data.fee);
121
- ```
122
-
123
- ## How The Flow Behaves
124
-
125
- 1. The SDK validates the recipient address.
126
- 2. The SDK asks the relay path for a fee quote.
127
- 3. The SDK checks that the wallet balance can cover `amount + fee`.
128
- 4. The transfer is submitted.
129
- 5. The relay pays TON gas and deducts the fee in USDT.
130
-
131
- ## Main Exports
132
-
133
- | Export | What it does |
134
- | ------------------------ | ---------------------------------------------------------- |
135
- | `setupTonGaslessWallet` | Creates the WDK-backed TON wallet and resolves the address |
136
- | `TonTransfer` | Checks balances, estimates fees, and sends transfers |
137
- | `getTonGaslessConfig` | Expands and validates the runtime config |
138
- | `tonUsdtTokenRoot` | Built-in TON USDT root address |
139
- | `usdtTonBaseUnits` | Converts human-readable USDT to base units |
140
- | `fromTonBaseUnitsToUsdt` | Converts base units back to readable USDT |
141
- | `getTonUsdtValue` | Utility helper for TON to USDT conversions |
142
-
143
- ## Safety Notes
144
-
145
- - `transferMaxFee` is capped by the SDK to prevent extreme fee deductions
146
- - invalid TON addresses are rejected before sending
147
- - self-transfers are blocked
148
- - the user must have enough USDT for both transfer amount and fee
149
-
150
- ## License
151
-
152
- MIT
1
+ # @gasfree-kit/ton-gasless
2
+
3
+ Gasless USDT transfers on TON through a sponsored relay.
4
+
5
+ With this package, the user only needs USDT. The relay pays the TON gas and charges a small fee back in USDT.
6
+
7
+ ## What This Package Does
8
+
9
+ - creates a WDK-backed TON wallet
10
+ - quotes the relay fee in USDT
11
+ - checks that balance covers transfer amount plus fee
12
+ - submits the gasless transfer
13
+ - returns a transfer context you can log or persist
14
+
15
+ ## Transfer Diagram
16
+
17
+ ```
18
+ ┌──────────────────────────┐
19
+ │ Your app │
20
+ └────────────┬─────────────┘
21
+ │
22
+ v
23
+ ┌──────────────────────────┐
24
+ │ @gasfree-kit/ton-gasless │
25
+ └──────┬─────────────┬─────┘
26
+ │ │
27
+ v v
28
+ ┌────────────┐ ┌───────────────┐
29
+ │ WDK TON │ │ Relay fee │
30
+ │ wallet │ │ quote (USDT) │
31
+ └──────┬─────┘ └───────┬───────┘
32
+ │ │
33
+ └───────┬───────┘
34
+ │
35
+ v
36
+ ┌──────────────────────────┐
37
+ │ Sponsored relay │
38
+ ├──────────────────────────┤
39
+ │ • Pays TON gas │
40
+ │ • Deducts USDT fee │
41
+ └────────────┬─────────────┘
42
+ │
43
+ v
44
+ ┌──────────────────────────┐
45
+ │ TON blockchain │
46
+ └──────────────────────────┘
47
+ ```
48
+
49
+ ```mermaid
50
+ flowchart TD
51
+ A["Your app"] --> B["@gasfree-kit/ton-gasless"]
52
+ B --> C["WDK TON wallet"]
53
+ B --> D["Relay fee quote"]
54
+ C --> E["Sponsored relay"]
55
+ D --> E
56
+ E -->|pays TON gas| F["TON blockchain"]
57
+ E -->|deducts fee| G["USDT commission"]
58
+ ```
59
+
60
+ ## Installation
61
+
62
+ ```bash
63
+ npm install @gasfree-kit/ton-gasless
64
+ ```
65
+
66
+ Peer dependencies:
67
+
68
+ ```bash
69
+ npm install @tetherto/wdk-wallet-ton-gasless tonweb
70
+ ```
71
+
72
+ ## Configuration
73
+
74
+ ```ts
75
+ import type { TonGaslessClientConfig } from '@gasfree-kit/ton-gasless';
76
+
77
+ const config: TonGaslessClientConfig = {
78
+ tonCenterUrl: 'https://toncenter.com/api/v2',
79
+ tonCenterApiKey: 'your-toncenter-api-key',
80
+ tonApiUrl: 'https://tonapi.io',
81
+ tonApiSecretKey: 'your-tonapi-secret-key',
82
+ // Optional:
83
+ // transferMaxFee: 1_000_000,
84
+ // usdtAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
85
+ };
86
+ ```
87
+
88
+ ### Config fields
89
+
90
+ | Field | Purpose |
91
+ | ----------------- | -------------------------------------------------- |
92
+ | `tonCenterUrl` | TON Center endpoint used by the wallet client |
93
+ | `tonCenterApiKey` | TON Center API key |
94
+ | `tonApiUrl` | TON API endpoint |
95
+ | `tonApiSecretKey` | TON API secret key |
96
+ | `transferMaxFee` | Maximum fee limit in base units, capped by the SDK |
97
+ | `usdtAddress` | Optional override for the TON USDT root |
98
+
99
+ ## Quick Start
100
+
101
+ ### 1. Generate a seed phrase
102
+
103
+ ```ts
104
+ import { generateSeedPhrase } from '@gasfree-kit/core';
105
+
106
+ const seedPhrase = await generateSeedPhrase();
107
+ ```
108
+
109
+ ### 2. Set up a wallet
110
+
111
+ ```ts
112
+ import { setupTonGaslessWallet } from '@gasfree-kit/ton-gasless';
113
+
114
+ const { wallet, account, address } = await setupTonGaslessWallet(seedPhrase, config);
115
+
116
+ console.log(address);
117
+ ```
118
+
119
+ If you need a specific derivation path:
120
+
121
+ ```ts
122
+ const walletResult = await setupTonGaslessWallet(seedPhrase, config, "0'/0/0");
123
+ ```
124
+
125
+ ### 3. Check USDT balance
126
+
127
+ ```ts
128
+ import { TonTransfer } from '@gasfree-kit/ton-gasless';
129
+
130
+ const balance = await TonTransfer.checkBalance(seedPhrase, config);
131
+
132
+ console.log(balance.data.usdBalance);
133
+ console.log(balance.data.tokenBalance);
134
+ ```
135
+
136
+ ### 4. Estimate the fee
137
+
138
+ ```ts
139
+ const estimate = await TonTransfer.getTransactionEstimateFee(
140
+ seedPhrase,
141
+ config,
142
+ '10.00',
143
+ 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
144
+ );
145
+
146
+ console.log(estimate.data.fee);
147
+ ```
148
+
149
+ ### 5. Execute the gasless transfer
150
+
151
+ ```ts
152
+ const result = await TonTransfer.transferUSDT(
153
+ seedPhrase,
154
+ config,
155
+ '50.00',
156
+ 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
157
+ );
158
+
159
+ console.log(result.data.transactionHash);
160
+ console.log(result.data.fee);
161
+ ```
162
+
163
+ ## How The Flow Behaves
164
+
165
+ 1. The SDK validates the recipient address.
166
+ 2. The SDK asks the relay path for a fee quote.
167
+ 3. The SDK checks that the wallet balance can cover `amount + fee`.
168
+ 4. The transfer is submitted.
169
+ 5. The relay pays TON gas and deducts the fee in USDT.
170
+
171
+ ## Main Exports
172
+
173
+ | Export | What it does |
174
+ | ------------------------ | ---------------------------------------------------------- |
175
+ | `setupTonGaslessWallet` | Creates the WDK-backed TON wallet and resolves the address |
176
+ | `TonTransfer` | Checks balances, estimates fees, and sends transfers |
177
+ | `getTonGaslessConfig` | Expands and validates the runtime config |
178
+ | `tonUsdtTokenRoot` | Built-in TON USDT root address |
179
+ | `usdtTonBaseUnits` | Converts human-readable USDT to base units |
180
+ | `fromTonBaseUnitsToUsdt` | Converts base units back to readable USDT |
181
+ | `getTonUsdtValue` | Utility helper for TON to USDT conversions |
182
+
183
+ ## Safety Notes
184
+
185
+ - `transferMaxFee` is capped by the SDK to prevent extreme fee deductions
186
+ - invalid TON addresses are rejected before sending
187
+ - self-transfers are blocked
188
+ - the user must have enough USDT for both transfer amount and fee
189
+
190
+ ## License
191
+
192
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gasfree-kit/ton-gasless",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Gasless USDT transfers on TON via sponsored relay",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -17,7 +17,7 @@
17
17
  "README.md"
18
18
  ],
19
19
  "dependencies": {
20
- "@gasfree-kit/core": "0.1.1"
20
+ "@gasfree-kit/core": "0.2.0"
21
21
  },
22
22
  "peerDependencies": {
23
23
  "@tetherto/wdk-wallet-ton-gasless": "^1.0.0-beta.4",