@gala-chain/launchpad-sdk 0.4.3 → 3.0.1

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 (135) hide show
  1. package/README.md +351 -77
  2. package/dist/examples/complete-sdk-demo.d.ts +22 -0
  3. package/dist/examples/complete-sdk-demo.d.ts.map +1 -0
  4. package/dist/index.cjs.js +1 -1
  5. package/dist/index.esm.js +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/src/LaunchpadSDK.d.ts +755 -0
  8. package/dist/src/LaunchpadSDK.d.ts.map +1 -0
  9. package/dist/{api → src/api}/LaunchpadAPI.d.ts +105 -67
  10. package/dist/src/api/LaunchpadAPI.d.ts.map +1 -0
  11. package/dist/{api → src/api}/dto/BondingCurveDTOs.d.ts +8 -5
  12. package/dist/src/api/dto/BondingCurveDTOs.d.ts.map +1 -0
  13. package/dist/src/api/dto/TransferTokenDto.d.ts +76 -0
  14. package/dist/src/api/dto/TransferTokenDto.d.ts.map +1 -0
  15. package/dist/src/auth/SignatureAuth.d.ts.map +1 -0
  16. package/dist/src/auth/types.d.ts.map +1 -0
  17. package/dist/src/config/environments.d.ts +45 -0
  18. package/dist/src/config/environments.d.ts.map +1 -0
  19. package/dist/{helpers → src/helpers}/sdk.d.ts +23 -13
  20. package/dist/src/helpers/sdk.d.ts.map +1 -0
  21. package/dist/src/helpers/wallet.d.ts.map +1 -0
  22. package/dist/src/index.d.ts +25 -0
  23. package/dist/src/index.d.ts.map +1 -0
  24. package/dist/src/services/BundleService.d.ts +197 -0
  25. package/dist/src/services/BundleService.d.ts.map +1 -0
  26. package/dist/src/services/DexService.d.ts +84 -0
  27. package/dist/src/services/DexService.d.ts.map +1 -0
  28. package/dist/src/services/GalaChainService.d.ts +254 -0
  29. package/dist/src/services/GalaChainService.d.ts.map +1 -0
  30. package/dist/src/services/LaunchpadService.d.ts +479 -0
  31. package/dist/src/services/LaunchpadService.d.ts.map +1 -0
  32. package/dist/src/services/SignatureService.d.ts.map +1 -0
  33. package/dist/src/services/TokenClassKeyService.d.ts.map +1 -0
  34. package/dist/src/services/TokenResolverService.d.ts +154 -0
  35. package/dist/src/services/TokenResolverService.d.ts.map +1 -0
  36. package/dist/src/services/WebSocketManager.d.ts.map +1 -0
  37. package/dist/{api → src}/services/WebSocketService.d.ts +4 -1
  38. package/dist/src/services/WebSocketService.d.ts.map +1 -0
  39. package/dist/{types → src/types}/comment.dto.d.ts +14 -5
  40. package/dist/src/types/comment.dto.d.ts.map +1 -0
  41. package/dist/{types → src/types}/common.d.ts +36 -1
  42. package/dist/src/types/common.d.ts.map +1 -0
  43. package/dist/{types → src/types}/dto.d.ts +19 -0
  44. package/dist/src/types/dto.d.ts.map +1 -0
  45. package/dist/{types → src/types}/launchpad.dto.d.ts +216 -30
  46. package/dist/src/types/launchpad.dto.d.ts.map +1 -0
  47. package/dist/{types → src/types}/launchpad.validation.d.ts +8 -8
  48. package/dist/src/types/launchpad.validation.d.ts.map +1 -0
  49. package/dist/src/types/options.dto.d.ts +281 -0
  50. package/dist/src/types/options.dto.d.ts.map +1 -0
  51. package/dist/src/types/result.types.d.ts +120 -0
  52. package/dist/src/types/result.types.d.ts.map +1 -0
  53. package/dist/{types → src/types}/trade.dto.d.ts +46 -19
  54. package/dist/src/types/trade.dto.d.ts.map +1 -0
  55. package/dist/src/types/transfer.dto.d.ts +161 -0
  56. package/dist/src/types/transfer.dto.d.ts.map +1 -0
  57. package/dist/{types → src/types}/user.dto.d.ts +98 -38
  58. package/dist/src/types/user.dto.d.ts.map +1 -0
  59. package/dist/src/types/websocket.types.d.ts +82 -0
  60. package/dist/src/types/websocket.types.d.ts.map +1 -0
  61. package/dist/src/utils/Logger.d.ts +136 -0
  62. package/dist/src/utils/Logger.d.ts.map +1 -0
  63. package/dist/src/utils/SignatureHelper.d.ts +77 -0
  64. package/dist/src/utils/SignatureHelper.d.ts.map +1 -0
  65. package/dist/src/utils/adapters.d.ts.map +1 -0
  66. package/dist/src/utils/agent-config.d.ts.map +1 -0
  67. package/dist/src/utils/date-utils.d.ts +39 -0
  68. package/dist/src/utils/date-utils.d.ts.map +1 -0
  69. package/dist/src/utils/http.d.ts.map +1 -0
  70. package/dist/src/utils/multipart.d.ts.map +1 -0
  71. package/dist/src/utils/number-utils.d.ts +57 -0
  72. package/dist/src/utils/number-utils.d.ts.map +1 -0
  73. package/dist/src/utils/precision-math.d.ts.map +1 -0
  74. package/dist/src/utils/slippage-utils.d.ts +70 -0
  75. package/dist/src/utils/slippage-utils.d.ts.map +1 -0
  76. package/dist/src/utils/tokenNormalizer.d.ts +111 -0
  77. package/dist/src/utils/tokenNormalizer.d.ts.map +1 -0
  78. package/dist/{utils → src/utils}/validation.d.ts +4 -4
  79. package/dist/src/utils/validation.d.ts.map +1 -0
  80. package/dist/{utils → src/utils}/wallet.d.ts +2 -2
  81. package/dist/src/utils/wallet.d.ts.map +1 -0
  82. package/package.json +10 -13
  83. package/dist/LaunchpadSDK.d.ts +0 -573
  84. package/dist/LaunchpadSDK.d.ts.map +0 -1
  85. package/dist/api/CommentAPI.d.ts +0 -119
  86. package/dist/api/CommentAPI.d.ts.map +0 -1
  87. package/dist/api/LaunchpadAPI.d.ts.map +0 -1
  88. package/dist/api/TradeAPI.d.ts +0 -164
  89. package/dist/api/TradeAPI.d.ts.map +0 -1
  90. package/dist/api/Trading.d.ts +0 -176
  91. package/dist/api/Trading.d.ts.map +0 -1
  92. package/dist/api/UserAPI.d.ts +0 -426
  93. package/dist/api/UserAPI.d.ts.map +0 -1
  94. package/dist/api/WebSocketAPI.d.ts +0 -156
  95. package/dist/api/WebSocketAPI.d.ts.map +0 -1
  96. package/dist/api/dto/BondingCurveDTOs.d.ts.map +0 -1
  97. package/dist/api/services/BundleService.d.ts +0 -105
  98. package/dist/api/services/BundleService.d.ts.map +0 -1
  99. package/dist/api/services/SignatureService.d.ts.map +0 -1
  100. package/dist/api/services/TokenClassKeyService.d.ts.map +0 -1
  101. package/dist/api/services/WebSocketManager.d.ts.map +0 -1
  102. package/dist/api/services/WebSocketService.d.ts.map +0 -1
  103. package/dist/auth/SignatureAuth.d.ts.map +0 -1
  104. package/dist/auth/types.d.ts.map +0 -1
  105. package/dist/helpers/sdk.d.ts.map +0 -1
  106. package/dist/helpers/wallet.d.ts.map +0 -1
  107. package/dist/index.d.ts +0 -49
  108. package/dist/index.d.ts.map +0 -1
  109. package/dist/types/comment.dto.d.ts.map +0 -1
  110. package/dist/types/common.d.ts.map +0 -1
  111. package/dist/types/dto.d.ts.map +0 -1
  112. package/dist/types/launchpad.dto.d.ts.map +0 -1
  113. package/dist/types/launchpad.validation.d.ts.map +0 -1
  114. package/dist/types/trade.dto.d.ts.map +0 -1
  115. package/dist/types/user.dto.d.ts.map +0 -1
  116. package/dist/utils/VaultCache.d.ts +0 -73
  117. package/dist/utils/VaultCache.d.ts.map +0 -1
  118. package/dist/utils/adapters.d.ts.map +0 -1
  119. package/dist/utils/agent-config.d.ts.map +0 -1
  120. package/dist/utils/http.d.ts.map +0 -1
  121. package/dist/utils/multipart.d.ts.map +0 -1
  122. package/dist/utils/precision-math.d.ts.map +0 -1
  123. package/dist/utils/validation.d.ts.map +0 -1
  124. package/dist/utils/wallet.d.ts.map +0 -1
  125. /package/dist/{auth → src/auth}/SignatureAuth.d.ts +0 -0
  126. /package/dist/{auth → src/auth}/types.d.ts +0 -0
  127. /package/dist/{helpers → src/helpers}/wallet.d.ts +0 -0
  128. /package/dist/{api → src}/services/SignatureService.d.ts +0 -0
  129. /package/dist/{api → src}/services/TokenClassKeyService.d.ts +0 -0
  130. /package/dist/{api → src}/services/WebSocketManager.d.ts +0 -0
  131. /package/dist/{utils → src/utils}/adapters.d.ts +0 -0
  132. /package/dist/{utils → src/utils}/agent-config.d.ts +0 -0
  133. /package/dist/{utils → src/utils}/http.d.ts +0 -0
  134. /package/dist/{utils → src/utils}/multipart.d.ts +0 -0
  135. /package/dist/{utils → src/utils}/precision-math.d.ts +0 -0
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # Gala Launchpad SDK v0.4.3
1
+ # Gala Launchpad SDK v3.0.1
2
2
 
3
3
  A comprehensive TypeScript SDK for the Gala Launchpad Backend API, providing type-safe authentication, trading, and real-time features for DeFi applications.
4
4
 
@@ -8,14 +8,13 @@ A comprehensive TypeScript SDK for the Gala Launchpad Backend API, providing typ
8
8
 
9
9
  ## 🚀 Features
10
10
 
11
- **Wallet Creation with Auto-Detection:**
11
+ **Clean Result Types with No Wrapper Overhead:**
12
12
 
13
- - **Auto-Detection**: Automatically detects private key vs mnemonic input format
14
- - **Flexible Input**: Supports 12/24-word mnemonics and 64-character hex private keys
15
- - **SDK Factory Functions**: Simplified SDK initialization with `createLaunchpadSDK()`
16
- - **Input Validation**: Built-in `validateWalletInput()` for format validation
17
- - **Test Support**: `createTestLaunchpadSDK()` for testing environments
18
- - **Flat API Design**: All methods directly on SDK root for simplicity
13
+ - **Direct Result Access**: Get clean, typed results without wrapper objects
14
+ - **Semantic Type Conversion**: Dates as Date objects, numbers as numbers, strings for precision
15
+ - **Comprehensive Type Safety**: Full TypeScript support with precise result interfaces
16
+ - **Zero Wrapper Overhead**: No more `result.data.success` - direct property access
17
+ - **Options Object Pattern**: All methods with 2+ parameters use clean options objects
19
18
 
20
19
  ### Developer Experience
21
20
 
@@ -27,35 +26,40 @@ const sdk = createLaunchpadSDK({
27
26
  wallet: 'your-private-key-or-mnemonic' // Auto-detects format!
28
27
  });
29
28
 
30
- // Or create wallet separately with auto-detection
31
- const wallet = createWallet('private-key-or-mnemonic');
32
- const sdk = createLaunchpadSDK({ wallet });
29
+ // Direct result access - no wrapper objects!
30
+ const pools = await sdk.fetchPools({ type: 'recent' });
31
+ console.log(`Found ${pools.total} pools`); // Direct property access
32
+ console.log(`Page ${pools.page} of ${pools.totalPages}`); // Clean pagination
33
+ console.log(`Has next: ${pools.hasNext}`); // Boolean convenience properties
33
34
 
34
- // Test SDK with defaults
35
- const testSDK = createTestLaunchpadSDK();
35
+ // Clean typed results everywhere
36
+ const balance = await sdk.fetchGalaBalance();
37
+ console.log(`Balance: ${balance.balance} GALA`); // Direct balance access
38
+ console.log(`Last updated: ${balance.lastUpdated.toISOString()}`); // Date object
36
39
  ```
37
40
 
38
- ## 📊 Flat API Architecture
41
+ ## 📊 Clean API Architecture
39
42
 
40
- **All methods directly on SDK root - simple and clean:**
43
+ **Direct result access with no wrapper overhead:**
41
44
 
42
45
  ```typescript
43
- // Everything is directly on sdk!
44
- await sdk.fetchPools({ type: 'recent' });
45
- await sdk.calculateBuyAmount({ tokenName: 'token', amount: '100', type: 'native' });
46
- await sdk.buy({ tokenName: 'token', amount: '100', type: 'native' });
47
- await sdk.fetchGalaBalance();
48
- await sdk.postComment({ tokenName: 'token', content: 'Great project!' });
46
+ // Get pools with direct property access
47
+ const pools = await sdk.fetchPools({ type: 'recent' });
48
+ console.log(pools.pools); // Direct access to pool array
49
+ console.log(pools.total); // Immediate pagination info
50
+ console.log(pools.hasNext); // Computed convenience properties
49
51
  ```
50
52
 
51
53
  ## 🚀 Key Features
52
54
 
53
55
  - **Type-Safe API Client**: Full TypeScript support with comprehensive type definitions
56
+ - **Clean Result Types**: Direct property access without wrapper objects
57
+ - **Options Object Pattern**: All multi-parameter methods use clean options objects
54
58
  - **Signature Authentication**: Ethereum wallet-based authentication with automatic signature generation
55
59
  - **Helper Functions**: Auto-detecting wallet creation and SDK factory functions
56
- - **Flat API Design**: All methods directly accessible on SDK root
57
60
  - **Pool Management**: Create, fetch, and check token pools on the launchpad
58
61
  - **Token Trading**: Buy and sell tokens with slippage protection via GalaChain
62
+ - **Token Transfers**: Transfer GALA and launchpad tokens between wallets with EIP-712 signatures
59
63
  - **User Operations**: Portfolio management, token balances, and account management
60
64
  - **Comment System**: Post and retrieve comments on token pools
61
65
  - **Comprehensive Validation**: Input validation and error handling for all operations
@@ -64,13 +68,13 @@ await sdk.postComment({ tokenName: 'token', content: 'Great project!' });
64
68
  ## 📦 Installation
65
69
 
66
70
  ```bash
67
- npm install @gala-chain/launchpad-sdk@^0.4.3
71
+ npm install @gala-chain/launchpad-sdk@^3.0.1
68
72
  ```
69
73
 
70
74
  Or with yarn:
71
75
 
72
76
  ```bash
73
- yarn add @gala-chain/launchpad-sdk@^0.4.3
77
+ yarn add @gala-chain/launchpad-sdk@^3.0.1
74
78
  ```
75
79
 
76
80
  ## 🏁 Quick Start
@@ -85,39 +89,66 @@ const sdk = createLaunchpadSDK({
85
89
  wallet: 'your-private-key-or-mnemonic' // Auto-detects format!
86
90
  });
87
91
 
88
- // Flat API - All methods directly on SDK root
92
+ // Clean, direct result access - All methods use options objects
89
93
 
90
- // Pool Management
94
+ // Pool Management - Direct result properties
91
95
  const pools = await sdk.fetchPools({ type: 'recent', limit: 10 });
96
+ console.log(`Found ${pools.total} pools across ${pools.totalPages} pages`);
97
+ console.log(`Current page: ${pools.page}, Has next: ${pools.hasNext}`);
98
+
92
99
  const badges = await sdk.fetchTokenBadges('dragnrkti');
93
- const details = await sdk.fetchSaleDetails('dragnrkti');
100
+ console.log(`Volume badges: ${badges.volumeBadges.length}`);
101
+ console.log(`Engagement badges: ${badges.engagementBadges.length}`);
94
102
 
95
- // Price Calculations
103
+ const details = await sdk.fetchPoolDetails('dragnrkti');
104
+ console.log(`Sale status: ${details.saleStatus}`);
105
+ console.log(`Native token quantity: ${details.nativeTokenQuantity}`);
106
+
107
+ // Price Calculations - Direct amount access
96
108
  const buyAmount = await sdk.calculateBuyAmount({
97
109
  tokenName: 'dragnrkti',
98
- amount: '1000000000000000000', // 1 GALA
110
+ amount: '1', // 1 GALA
99
111
  type: 'native'
100
112
  });
113
+ console.log(`Buy amount: ${buyAmount.amount}`);
114
+ console.log(`Transaction fee: ${buyAmount.transactionFee}`);
101
115
 
102
- // Trading Operations
116
+ // Trading Operations - Required expectedAmount and slippageToleranceFactor
103
117
  const buyResult = await sdk.buy({
104
118
  tokenName: 'dragnrkti',
105
- amount: '1000000000000000000',
119
+ amount: '1',
106
120
  type: 'native',
107
- slippage: 5
121
+ expectedAmount: buyAmount.amount, // Required: from calculation
122
+ slippageToleranceFactor: 0.05 // Required: decimal format (5% slippage)
108
123
  });
124
+ console.log(`Transaction ID: ${buyResult.transactionId}`);
109
125
 
110
- // Data & Analytics
126
+ // Data & Analytics - Clean pagination
111
127
  const trades = await sdk.fetchTrades({ tokenName: 'dragnrkti' });
128
+ console.log(`Found ${trades.total} trades`);
129
+ console.log(`Page ${trades.page} of ${trades.totalPages}`);
130
+ trades.trades.forEach(trade => {
131
+ console.log(`Trade: ${trade.tradeType} ${trade.tokenAmount} at ${trade.createdAt.toISOString()}`);
132
+ });
133
+
112
134
  const comments = await sdk.fetchComments({ tokenName: 'dragnrkti' });
113
- const balance = await sdk.fetchGalaBalance();
135
+ console.log(`${comments.total} comments found`);
136
+
137
+ // User Operations - Direct balance access
138
+ const galaBalance = await sdk.fetchGalaBalance();
139
+ console.log(`GALA Balance: ${galaBalance.balance}`);
140
+ console.log(`Last updated: ${galaBalance.lastUpdated.toISOString()}`);
114
141
 
115
- // User Operations
116
- const profile = await sdk.fetchProfile();
117
142
  const tokenBalance = await sdk.fetchTokenBalance({
118
143
  tokenName: 'dragnrkti',
119
144
  walletAddress: sdk.getAddress()
120
145
  });
146
+ console.log(`Token balance: ${tokenBalance.quantity}`);
147
+ console.log(`USD value: $${tokenBalance.holdingPriceUsd}`);
148
+
149
+ // Profile - Direct user data
150
+ const profile = await sdk.fetchProfile();
151
+ console.log(`Profile name: ${profile.fullName || 'Not set'}`);
121
152
  ```
122
153
 
123
154
  ### Manual SDK Creation (Alternative)
@@ -137,11 +168,12 @@ const sdk = new LaunchpadSDK({
137
168
  debug: false
138
169
  });
139
170
 
140
- // Same flat API available
171
+ // Same clean API available
141
172
  const pools = await sdk.fetchPools({ type: 'recent' });
173
+ console.log(`${pools.total} pools found`);
142
174
  ```
143
175
 
144
- ## 🎯 Complete Example: Trading Flow
176
+ ## 🎯 Complete Example: Trading Flow with Clean Results
145
177
 
146
178
  ```typescript
147
179
  import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
@@ -151,86 +183,208 @@ const sdk = createLaunchpadSDK({
151
183
  wallet: 'your-private-key-or-mnemonic'
152
184
  });
153
185
 
154
- // 2. Check available pools
186
+ // 2. Check available pools - direct access to results
155
187
  const pools = await sdk.fetchPools({
156
188
  type: 'recent',
157
189
  limit: 10
158
190
  });
159
191
 
160
- // 3. Get price quote
192
+ console.log(`Found ${pools.total} pools across ${pools.totalPages} pages`);
193
+ pools.pools.forEach(pool => {
194
+ console.log(`Pool: ${pool.tokenName} created at ${pool.createdAt}`);
195
+ });
196
+
197
+ // 3. Get price quote - direct amount access
161
198
  const quote = await sdk.calculateBuyAmount({
162
199
  tokenName: 'tinyevil',
163
200
  amount: '100',
164
201
  type: 'native'
165
202
  });
166
203
 
167
- console.log(`Buying 100 GALA worth of tokens will get you: ${quote.outTokenAmount} TINYEVIL`);
204
+ console.log(`Buying 100 GALA worth will get you: ${quote.amount} TINYEVIL`);
205
+ console.log(`Transaction fee: ${quote.transactionFee} GALA`);
206
+ console.log(`Reverse bonding curve fee: ${quote.reverseBondingCurveFee} GALA`);
168
207
 
169
- // 4. Execute trade with slippage protection
208
+ // 4. Execute trade with slippage protection - requires expectedAmount
170
209
  const buyResult = await sdk.buy({
171
210
  tokenName: 'tinyevil',
172
211
  amount: '100',
173
212
  type: 'native',
174
- slippage: 5 // 5% slippage tolerance
213
+ expectedAmount: quote.amount, // Required: from calculation above
214
+ slippageToleranceFactor: 0.05 // Required: decimal format for 5% slippage
175
215
  });
176
216
 
177
- // 5. Check trade history
217
+ console.log(`Transaction submitted: ${buyResult.transactionId}`);
218
+
219
+ // 5. Check trade history - clean pagination
178
220
  const trades = await sdk.fetchTrades({ tokenName: 'tinyevil' });
221
+ console.log(`Found ${trades.total} trades on page ${trades.page}`);
222
+ console.log(`Has more pages: ${trades.hasNext}`);
223
+
224
+ trades.trades.forEach(trade => {
225
+ console.log(`${trade.tradeType}: ${trade.tokenAmount} at ${trade.createdAt.toISOString()}`);
226
+ });
179
227
 
180
228
  // 6. Post a comment about your trade
181
- await sdk.postComment({
229
+ const comment = await sdk.postComment({
182
230
  tokenName: 'tinyevil',
183
231
  content: 'Just bought some tokens! Great project!'
184
232
  });
185
233
 
186
- // 7. Check your balance
187
- const balance = await sdk.fetchGalaBalance();
234
+ console.log(`Comment posted with ID: ${comment.id}`);
235
+
236
+ // 7. Check your balance - direct balance access
237
+ const galaBalance = await sdk.fetchGalaBalance();
238
+ console.log(`GALA Balance: ${galaBalance.balance}`);
239
+ console.log(`Decimals: ${galaBalance.decimals}`);
240
+ console.log(`Last updated: ${galaBalance.lastUpdated.toISOString()}`);
241
+
188
242
  const tokenBalance = await sdk.fetchTokenBalance({
189
243
  tokenName: 'tinyevil',
190
244
  walletAddress: sdk.getAddress()
191
245
  });
192
246
 
193
- console.log(`GALA Balance: ${balance.balance}`);
194
- console.log(`TINYEVIL Balance: ${tokenBalance.balance}`);
247
+ console.log(`TINYEVIL Balance: ${tokenBalance.quantity}`);
248
+ console.log(`USD Value: $${tokenBalance.holdingPriceUsd}`);
249
+ console.log(`GALA Value: ${tokenBalance.holdingPriceGala} GALA`);
250
+ console.log(`Finalized: ${tokenBalance.isFinalized}`);
251
+ ```
252
+
253
+ ## 💸 Transfer Operations
254
+
255
+ Transfer GALA and launchpad tokens between wallets with EIP-712 signatures:
256
+
257
+ ```typescript
258
+ import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
259
+
260
+ const sdk = createLaunchpadSDK({
261
+ wallet: 'your-private-key-or-mnemonic'
262
+ });
263
+
264
+ // Transfer GALA tokens - direct result access
265
+ const galaTransfer = await sdk.transferGala({
266
+ recipientAddress: 'eth|1234567890abcdef1234567890abcdef12345678', // or 0x format
267
+ amount: '1', // 1 GALA
268
+ uniqueKey: 'galaconnect-operation-my-transfer-123' // Optional for idempotency
269
+ });
270
+
271
+ console.log(`GALA Transfer ID: ${galaTransfer.transactionId}`);
272
+ console.log(`Status: ${galaTransfer.status}`);
273
+
274
+ // Transfer launchpad tokens - direct result access
275
+ const tokenTransfer = await sdk.transferToken({
276
+ to: '0x9876543210fedcba9876543210fedcba98765432', // or eth| format
277
+ tokenName: 'tinyevil',
278
+ amount: '1000000', // Token amount in smallest unit
279
+ uniqueKey: 'galaconnect-operation-token-transfer-456' // Optional for idempotency
280
+ });
281
+
282
+ console.log(`Token Transfer ID: ${tokenTransfer.transactionId}`);
283
+ console.log(`Status: ${tokenTransfer.status}`);
195
284
  ```
196
285
 
197
- ## 🎯 Available Methods
286
+ ### Transfer Features
287
+ - **EIP-712 Signatures**: Secure blockchain transactions
288
+ - **Address Format Handling**: Supports both `0x` and `eth|` formats
289
+ - **Idempotency**: Optional unique keys prevent duplicate transfers (must use `galaswap-operation-` or `galaconnect-operation-` prefix)
290
+ - **Comprehensive Validation**: Amount limits, address formats, token names, unique key formats
291
+ - **GalaChain Integration**: Direct transfers via GalaChain gateway
292
+ - **Error Handling**: Detailed error types for different failure scenarios
293
+
294
+ ## 🎯 Available Methods & Result Types
198
295
 
199
296
  ### **Fetch Operations**
200
- - `fetchPools(options?)` - Get pools (recent, popular, search)
201
- - `fetchTokenDistribution(tokenName)` - Token holder distribution
202
- - `fetchTokenBadges(tokenName)` - Volume and engagement badges
203
- - `fetchSaleDetails(tokenName)` - Token sale information
204
- - `fetchGraphData(options)` - Price chart data
205
- - `fetchTrades(options)` - Trade history
206
- - `fetchGalaBalance(walletAddress?)` - User GALA balance
207
- - `fetchTokenBalance(options)` - User token balance
208
- - `fetchComments(options)` - Token comments
209
- - `fetchProfile(walletAddress?)` - User profile
297
+
298
+ ```typescript
299
+ // Pool Management
300
+ fetchPools(options?): Promise<PoolsResult>
301
+ // Returns: { pools, page, limit, total, totalPages, hasNext, hasPrevious }
302
+
303
+ fetchTokenDistribution(tokenName): Promise<TokenDistributionResult>
304
+ // Returns: { holders, totalSupply, totalHolders, lastUpdated }
305
+
306
+ fetchTokenBadges(tokenName): Promise<TokenBadgesResult>
307
+ // Returns: { volumeBadges, engagementBadges }
308
+
309
+ fetchPoolDetails(tokenName): Promise<PoolDetailsData>
310
+ // Returns: { basePrice, maxSupply, saleStatus, nativeTokenQuantity, ... }
311
+
312
+ fetchVolumeData(options): Promise<GraphDataResult>
313
+ // Returns: { dataPoints }
314
+
315
+ // Trade & User Data
316
+ fetchTrades(options): Promise<TradesResult>
317
+ // Returns: { trades, page, limit, total, totalPages, hasNext, hasPrevious }
318
+
319
+ fetchGalaBalance(walletAddress?): Promise<GalaBalanceInfo>
320
+ // Returns: { userAddress, balance, decimals, lastUpdated }
321
+
322
+ fetchTokenBalance(options): Promise<TokenBalanceInfo>
323
+ // Returns: { quantity, holdingPriceUsd, holdingPriceGala, isFinalized, ... }
324
+
325
+ fetchComments(options): Promise<CommentsResult>
326
+ // Returns: { comments, page, limit, total, totalPages, hasNext, hasPrevious }
327
+
328
+ fetchProfile(walletAddress?): Promise<UserProfile>
329
+ // Returns: { fullName, profileImage, walletAddress, ... }
330
+ ```
210
331
 
211
332
  ### **Calculate Operations**
212
- - `calculateBuyAmount(options)` - Calculate GALA cost for tokens
213
- - `calculateSellAmount(options)` - Calculate GALA received from tokens
214
- - `calculateInitialBuyAmount(options)` - Pre-mint calculations
333
+
334
+ ```typescript
335
+ // Price Calculations
336
+ calculateBuyAmount(options): Promise<AmountCalculationResult>
337
+ // Returns: { amount, reverseBondingCurveFee, transactionFee }
338
+
339
+ calculateSellAmount(options): Promise<AmountCalculationResult>
340
+ // Returns: { amount, reverseBondingCurveFee, transactionFee }
341
+
342
+ calculateInitialBuyAmount(options): Promise<AmountCalculationResult>
343
+ // Returns: { amount, reverseBondingCurveFee, transactionFee }
344
+ ```
215
345
 
216
346
  ### **Trading Operations**
217
- - `buy(options)` - Buy tokens with slippage protection
218
- - `sell(options)` - Sell tokens with slippage protection
347
+
348
+ ```typescript
349
+ // Buy/Sell Tokens
350
+ buy(options): Promise<TransactionResult>
351
+ // Options: { tokenName, amount, type, expectedAmount, slippageToleranceFactor }
352
+ // Returns: { transactionId, status, ... }
353
+
354
+ sell(options): Promise<TransactionResult>
355
+ // Options: { tokenName, amount, type, expectedAmount, slippageToleranceFactor }
356
+ // Returns: { transactionId, status, ... }
357
+ ```
219
358
 
220
359
  ### **Content Operations**
221
- - `postComment(options)` - Post comment on token
222
- - `createTokenAndPool(data)` - Create new token sale
223
- - `uploadTokenImage(options)` - Upload token image
224
- - `updateProfile(data)` - Update user profile
225
- - `uploadProfileImage(options)` - Upload profile image
360
+
361
+ ```typescript
362
+ // Comments & Content
363
+ postComment(options): Promise<CommentResult>
364
+ // Returns: { id, content, createdAt, ... }
365
+
366
+ // Token Creation & Management
367
+ launchToken(data): Promise<LaunchTokenResult>
368
+ // Returns: { transactionId, status, ... }
369
+
370
+ uploadTokenImage(options): Promise<ImageUploadResult>
371
+ // Returns: { imageUrl, success, ... }
372
+
373
+ // Profile Management
374
+ updateProfile(data): Promise<ProfileUpdateResult>
375
+ // Returns: { success, data, ... }
376
+
377
+ uploadProfileImage(options): Promise<ImageUploadResult>
378
+ // Returns: { imageUrl, success, ... }
379
+ ```
226
380
 
227
381
  ### **Validation & Utilities**
228
- - `isTokenNameAvailable(tokenName)` - Check name availability
229
- - `isTokenSymbolAvailable(symbol)` - Check symbol availability
230
- - `getAddress()` - Get backend format address (eth|...)
231
- - `getEthereumAddress()` - Get Ethereum format address (0x...)
232
- - `resolveVaultAddress(tokenName)` - Get token vault address
233
- - `cleanup()` - Cleanup resources
382
+ - `isTokenNameAvailable(tokenName: string): Promise<boolean>`
383
+ - `isTokenSymbolAvailable(symbol: string): Promise<boolean>`
384
+ - `getAddress(): string` - Get backend format address (eth|...)
385
+ - `getEthereumAddress(): string` - Get Ethereum format address (0x...)
386
+ - `resolveVaultAddress(tokenName: string): Promise<string>`
387
+ - `cleanup(): void` - Cleanup resources
234
388
 
235
389
  ## 🔧 Helper Functions
236
390
 
@@ -300,10 +454,130 @@ npm run lint
300
454
  ## 📚 Documentation
301
455
 
302
456
  - [SDK Method Reference](./SDK-METHOD-GRAPH.md) - Complete flat API reference
303
- - [AI Agent Guide](./docs/AI_AGENT_GUIDE.md) - Integration with AI agents
457
+ - [Clean Result Types Migration Guide](./docs/CLEAN_RESULT_TYPES_MIGRATION.md) - Migration guide for clean result types
458
+ - [Service Architecture Migration Guide](./docs/SERVICE_ARCHITECTURE_MIGRATION.md) - Guide for v3.1.0 service-based architecture
304
459
  - [API Documentation](../../API.md) - Detailed API documentation
305
460
  - [Examples](./examples/) - Code examples and demos
306
461
 
462
+ ## 🏗️ Architecture
463
+
464
+ The SDK uses a **service-based architecture** with backend-aligned services:
465
+
466
+ ### Backend-Aligned Services
467
+
468
+ ```typescript
469
+ // Each service maps 1:1 to a specific backend
470
+ import {
471
+ LaunchpadService, // → launchpad-backend (pools, trades, comments, profiles)
472
+ GalaChainService, // → galachain-gateway (balances, transfers, pool details)
473
+ DexService, // → dex-api (spot prices)
474
+ BundleService, // → bundle-backend (transaction bundling, trading)
475
+ WebSocketService // → WebSocket endpoint (real-time monitoring)
476
+ } from '@gala-chain/launchpad-sdk';
477
+ ```
478
+
479
+ ### Service Responsibilities
480
+
481
+ **LaunchpadService** - Launchpad Backend Operations
482
+ - Pool management (fetch, create, check)
483
+ - Trade history
484
+ - Comments (post, fetch)
485
+ - User profiles
486
+ - Token images
487
+ - Faucet operations
488
+
489
+ **GalaChainService** - Blockchain Operations
490
+ - GALA balance queries
491
+ - Token balance queries
492
+ - Token transfers (GALA & launchpad tokens)
493
+ - Pool details from bonding curve contracts
494
+ - Token resolution
495
+
496
+ **DexService** - Price Queries
497
+ - Spot price fetching
498
+ - Multi-token price queries
499
+
500
+ **BundleService** - Transaction Bundling
501
+ - Buy token operations
502
+ - Sell token operations
503
+ - Slippage protection
504
+ - Transaction bundling
505
+
506
+ **WebSocketService** - Real-time Features
507
+ - Transaction monitoring
508
+ - Status updates
509
+ - Connection management
510
+
511
+ ### Benefits of Service Architecture
512
+
513
+ ✅ **Clear Separation**: Each service has a single backend responsibility
514
+ ✅ **Type Safety**: Full TypeScript support across all services
515
+ ✅ **Testability**: Services can be tested independently
516
+ ✅ **Maintainability**: Easy to locate and update backend-specific logic
517
+
518
+ ### 🤖 AI Agent Integration
519
+
520
+ The SDK includes comprehensive utilities for AI agent development:
521
+
522
+ ```typescript
523
+ import { AgentConfig } from '@gala-chain/launchpad-sdk';
524
+
525
+ // Quick setup with intelligent defaults
526
+ const { sdk, validation } = await AgentConfig.quickSetup({
527
+ environment: 'development',
528
+ autoValidate: true
529
+ });
530
+
531
+ console.log(`Ready: ${validation.ready}`);
532
+ console.log(`Can trade: ${validation.capabilities.canTrade}`);
533
+ ```
534
+
535
+ For comprehensive AI agent integration, see:
536
+ - [AI Agent Integration Guide](./docs/AI-AGENT-GUIDE.md) - Complete guide for agent development
537
+ - [MCP Tool Specification](./docs/MCP-TOOL-SPECIFICATION.md) - Blueprint for MCP server creation
538
+ - [Agent Examples](./docs/agent-examples/) - Working code examples
539
+
540
+ ## 🎯 Clean Result Types Architecture
541
+
542
+ ### Key Benefits
543
+
544
+ ✅ **Direct Property Access**: No more `result.data.success` chains
545
+ ✅ **Type Safety**: Full TypeScript IntelliSense for all result properties
546
+ ✅ **Semantic Types**: Dates as Date objects, numbers as numbers
547
+ ✅ **Computed Properties**: `hasNext`, `hasPrevious` for convenience
548
+ ✅ **Zero Wrapper Overhead**: Clean, direct access to all result data
549
+ ✅ **Options Object Pattern**: All multi-parameter methods use options objects
550
+
551
+ ### Result Type Examples
552
+
553
+ ```typescript
554
+ // Pool results with pagination
555
+ interface PoolsResult {
556
+ pools: PoolData[]; // Direct pool array
557
+ page: number; // Current page
558
+ total: number; // Total items
559
+ hasNext: boolean; // Computed convenience
560
+ // ... more properties
561
+ }
562
+
563
+ // Token balance with typed values
564
+ interface TokenBalanceInfo {
565
+ quantity: string; // Token amount (string for precision)
566
+ holdingPriceUsd: number; // USD value (number for math)
567
+ lastUpdated: Date; // Date object (not string)
568
+ isFinalized: boolean; // Boolean flag
569
+ // ... more properties
570
+ }
571
+
572
+ // Trading results
573
+ interface AmountCalculationResult {
574
+ amount: string; // Calculated amount
575
+ transactionFee: string; // Fee breakdown
576
+ reverseBondingCurveFee: string; // RBC fee
577
+ // Direct access to all calculation data
578
+ }
579
+ ```
580
+
307
581
  ## 🚀 Environment URLs
308
582
 
309
583
  - **Development**: `https://lpad-backend-dev1.defi.gala.com`
@@ -0,0 +1,22 @@
1
+ #!/usr/bin/env tsx
2
+ /**
3
+ * 🚀 GALA LAUNCHPAD SDK - COMPLETE DEMONSTRATION
4
+ *
5
+ * This is the ONLY demo you need! It covers every feature of the SDK:
6
+ *
7
+ * ✅ Token Creation & Management
8
+ * ✅ All Trading Operations (buy/sell with native/exact amounts)
9
+ * ✅ User Profile & Social Features
10
+ * ✅ Transfer Operations (GALA & Tokens)
11
+ * ✅ Data Fetching (pools, balances, history)
12
+ * ✅ Automatic Transaction Confirmation (WebSocket internal)
13
+ * ✅ Error Handling & Recovery
14
+ *
15
+ * Run with: npx tsx examples/complete-sdk-demo.ts
16
+ */
17
+ /**
18
+ * 🎯 Main demo function
19
+ */
20
+ declare function runCompleteSDKDemo(): Promise<void>;
21
+ export { runCompleteSDKDemo };
22
+ //# sourceMappingURL=complete-sdk-demo.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"complete-sdk-demo.d.ts","sourceRoot":"","sources":["../../examples/complete-sdk-demo.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;GAcG;AAiNH;;GAEG;AACH,iBAAe,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CA6+BjD;AAYD,OAAO,EAAE,kBAAkB,EAAE,CAAC"}