@gasfree-kit/ton-gasless 0.1.0 → 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.
- package/README.md +192 -0
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +4 -4
- package/dist/index.mjs +3 -3
- package/package.json +4 -3
package/README.md
ADDED
|
@@ -0,0 +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
|
+
```
|
|
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/dist/index.d.mts
CHANGED
|
@@ -37,7 +37,7 @@ declare function setupTonGaslessWallet(seedPhrase: string, config: TonGaslessCli
|
|
|
37
37
|
address: string;
|
|
38
38
|
}>;
|
|
39
39
|
|
|
40
|
-
declare class
|
|
40
|
+
declare class TonTransfer {
|
|
41
41
|
/**
|
|
42
42
|
* Get transaction fee estimate for a gasless USDT transfer on TON.
|
|
43
43
|
* The gasless commission is returned in USDT (paymaster token units).
|
|
@@ -56,7 +56,7 @@ declare class TonGaslessTetherTransfer {
|
|
|
56
56
|
message: string;
|
|
57
57
|
success: boolean;
|
|
58
58
|
data: {
|
|
59
|
-
|
|
59
|
+
tokenBalance: string;
|
|
60
60
|
decimals: number;
|
|
61
61
|
usdBalance: string;
|
|
62
62
|
};
|
|
@@ -98,4 +98,4 @@ declare function fromTonBaseUnitsToUsdt(amount: bigint, dec?: number): string;
|
|
|
98
98
|
*/
|
|
99
99
|
declare function getTonUsdtValue(amountInBaseUnits: bigint, exchangeRate: number): number;
|
|
100
100
|
|
|
101
|
-
export { type TonGaslessClientConfig, type TonGaslessNetworkConfig,
|
|
101
|
+
export { type TonGaslessClientConfig, type TonGaslessNetworkConfig, TonTransfer, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };
|
package/dist/index.d.ts
CHANGED
|
@@ -37,7 +37,7 @@ declare function setupTonGaslessWallet(seedPhrase: string, config: TonGaslessCli
|
|
|
37
37
|
address: string;
|
|
38
38
|
}>;
|
|
39
39
|
|
|
40
|
-
declare class
|
|
40
|
+
declare class TonTransfer {
|
|
41
41
|
/**
|
|
42
42
|
* Get transaction fee estimate for a gasless USDT transfer on TON.
|
|
43
43
|
* The gasless commission is returned in USDT (paymaster token units).
|
|
@@ -56,7 +56,7 @@ declare class TonGaslessTetherTransfer {
|
|
|
56
56
|
message: string;
|
|
57
57
|
success: boolean;
|
|
58
58
|
data: {
|
|
59
|
-
|
|
59
|
+
tokenBalance: string;
|
|
60
60
|
decimals: number;
|
|
61
61
|
usdBalance: string;
|
|
62
62
|
};
|
|
@@ -98,4 +98,4 @@ declare function fromTonBaseUnitsToUsdt(amount: bigint, dec?: number): string;
|
|
|
98
98
|
*/
|
|
99
99
|
declare function getTonUsdtValue(amountInBaseUnits: bigint, exchangeRate: number): number;
|
|
100
100
|
|
|
101
|
-
export { type TonGaslessClientConfig, type TonGaslessNetworkConfig,
|
|
101
|
+
export { type TonGaslessClientConfig, type TonGaslessNetworkConfig, TonTransfer, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };
|
package/dist/index.js
CHANGED
|
@@ -30,7 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
|
|
|
30
30
|
// src/index.ts
|
|
31
31
|
var index_exports = {};
|
|
32
32
|
__export(index_exports, {
|
|
33
|
-
|
|
33
|
+
TonTransfer: () => TonTransfer,
|
|
34
34
|
fromTonBaseUnitsToUsdt: () => fromTonBaseUnitsToUsdt,
|
|
35
35
|
getTonGaslessConfig: () => getTonGaslessConfig,
|
|
36
36
|
getTonUsdtValue: () => getTonUsdtValue,
|
|
@@ -112,7 +112,7 @@ function getTonUsdtValue(amountInBaseUnits, exchangeRate) {
|
|
|
112
112
|
}
|
|
113
113
|
|
|
114
114
|
// src/tonGaslessTetherTransfer.ts
|
|
115
|
-
var
|
|
115
|
+
var TonTransfer = class {
|
|
116
116
|
/**
|
|
117
117
|
* Get transaction fee estimate for a gasless USDT transfer on TON.
|
|
118
118
|
* The gasless commission is returned in USDT (paymaster token units).
|
|
@@ -150,7 +150,7 @@ var TonGaslessTetherTransfer = class {
|
|
|
150
150
|
message: "TON balances retrieved successfully",
|
|
151
151
|
success: true,
|
|
152
152
|
data: {
|
|
153
|
-
|
|
153
|
+
tokenBalance: balance.toString(),
|
|
154
154
|
decimals: 6,
|
|
155
155
|
usdBalance: String(usdBalance)
|
|
156
156
|
}
|
|
@@ -230,7 +230,7 @@ var TonGaslessTetherTransfer = class {
|
|
|
230
230
|
};
|
|
231
231
|
// Annotate the CommonJS export names for ESM import in node:
|
|
232
232
|
0 && (module.exports = {
|
|
233
|
-
|
|
233
|
+
TonTransfer,
|
|
234
234
|
fromTonBaseUnitsToUsdt,
|
|
235
235
|
getTonGaslessConfig,
|
|
236
236
|
getTonUsdtValue,
|
package/dist/index.mjs
CHANGED
|
@@ -74,7 +74,7 @@ function getTonUsdtValue(amountInBaseUnits, exchangeRate) {
|
|
|
74
74
|
}
|
|
75
75
|
|
|
76
76
|
// src/tonGaslessTetherTransfer.ts
|
|
77
|
-
var
|
|
77
|
+
var TonTransfer = class {
|
|
78
78
|
/**
|
|
79
79
|
* Get transaction fee estimate for a gasless USDT transfer on TON.
|
|
80
80
|
* The gasless commission is returned in USDT (paymaster token units).
|
|
@@ -112,7 +112,7 @@ var TonGaslessTetherTransfer = class {
|
|
|
112
112
|
message: "TON balances retrieved successfully",
|
|
113
113
|
success: true,
|
|
114
114
|
data: {
|
|
115
|
-
|
|
115
|
+
tokenBalance: balance.toString(),
|
|
116
116
|
decimals: 6,
|
|
117
117
|
usdBalance: String(usdBalance)
|
|
118
118
|
}
|
|
@@ -191,7 +191,7 @@ var TonGaslessTetherTransfer = class {
|
|
|
191
191
|
}
|
|
192
192
|
};
|
|
193
193
|
export {
|
|
194
|
-
|
|
194
|
+
TonTransfer,
|
|
195
195
|
fromTonBaseUnitsToUsdt,
|
|
196
196
|
getTonGaslessConfig,
|
|
197
197
|
getTonUsdtValue,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gasfree-kit/ton-gasless",
|
|
3
|
-
"version": "0.
|
|
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",
|
|
@@ -13,10 +13,11 @@
|
|
|
13
13
|
}
|
|
14
14
|
},
|
|
15
15
|
"files": [
|
|
16
|
-
"dist"
|
|
16
|
+
"dist",
|
|
17
|
+
"README.md"
|
|
17
18
|
],
|
|
18
19
|
"dependencies": {
|
|
19
|
-
"@gasfree-kit/core": "0.
|
|
20
|
+
"@gasfree-kit/core": "0.2.0"
|
|
20
21
|
},
|
|
21
22
|
"peerDependencies": {
|
|
22
23
|
"@tetherto/wdk-wallet-ton-gasless": "^1.0.0-beta.4",
|