@galaxy-kj/core-stellar-sdk 2.0.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 (179) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +576 -0
  3. package/dist/claimable-balances/claimable-balance-manager.d.ts +99 -0
  4. package/dist/claimable-balances/claimable-balance-manager.d.ts.map +1 -0
  5. package/dist/claimable-balances/claimable-balance-manager.js +352 -0
  6. package/dist/claimable-balances/claimable-balance-manager.js.map +1 -0
  7. package/dist/claimable-balances/helpers.d.ts +66 -0
  8. package/dist/claimable-balances/helpers.d.ts.map +1 -0
  9. package/dist/claimable-balances/helpers.js +179 -0
  10. package/dist/claimable-balances/helpers.js.map +1 -0
  11. package/dist/claimable-balances/index.d.ts +12 -0
  12. package/dist/claimable-balances/index.d.ts.map +1 -0
  13. package/dist/claimable-balances/index.js +14 -0
  14. package/dist/claimable-balances/index.js.map +1 -0
  15. package/dist/claimable-balances/predicate-builder.d.ts +66 -0
  16. package/dist/claimable-balances/predicate-builder.d.ts.map +1 -0
  17. package/dist/claimable-balances/predicate-builder.js +169 -0
  18. package/dist/claimable-balances/predicate-builder.js.map +1 -0
  19. package/dist/claimable-balances/types.d.ts +123 -0
  20. package/dist/claimable-balances/types.d.ts.map +1 -0
  21. package/dist/claimable-balances/types.js +9 -0
  22. package/dist/claimable-balances/types.js.map +1 -0
  23. package/dist/hooks/use-stellar.d.ts +48 -0
  24. package/dist/hooks/use-stellar.d.ts.map +1 -0
  25. package/dist/hooks/use-stellar.js +510 -0
  26. package/dist/hooks/use-stellar.js.map +1 -0
  27. package/dist/index.d.ts +19 -0
  28. package/dist/index.d.ts.map +1 -0
  29. package/dist/index.js +28 -0
  30. package/dist/index.js.map +1 -0
  31. package/dist/liquidity-pools/calculations.d.ts +113 -0
  32. package/dist/liquidity-pools/calculations.d.ts.map +1 -0
  33. package/dist/liquidity-pools/calculations.js +291 -0
  34. package/dist/liquidity-pools/calculations.js.map +1 -0
  35. package/dist/liquidity-pools/helpers.d.ts +102 -0
  36. package/dist/liquidity-pools/helpers.d.ts.map +1 -0
  37. package/dist/liquidity-pools/helpers.js +219 -0
  38. package/dist/liquidity-pools/helpers.js.map +1 -0
  39. package/dist/liquidity-pools/index.d.ts +13 -0
  40. package/dist/liquidity-pools/index.d.ts.map +1 -0
  41. package/dist/liquidity-pools/index.js +18 -0
  42. package/dist/liquidity-pools/index.js.map +1 -0
  43. package/dist/liquidity-pools/liquidity-pool-manager.d.ts +106 -0
  44. package/dist/liquidity-pools/liquidity-pool-manager.d.ts.map +1 -0
  45. package/dist/liquidity-pools/liquidity-pool-manager.js +387 -0
  46. package/dist/liquidity-pools/liquidity-pool-manager.js.map +1 -0
  47. package/dist/liquidity-pools/types.d.ts +135 -0
  48. package/dist/liquidity-pools/types.d.ts.map +1 -0
  49. package/dist/liquidity-pools/types.js +6 -0
  50. package/dist/liquidity-pools/types.js.map +1 -0
  51. package/dist/liquidity-pools/validation.d.ts +75 -0
  52. package/dist/liquidity-pools/validation.d.ts.map +1 -0
  53. package/dist/liquidity-pools/validation.js +218 -0
  54. package/dist/liquidity-pools/validation.js.map +1 -0
  55. package/dist/services/stellar-service.d.ts +231 -0
  56. package/dist/services/stellar-service.d.ts.map +1 -0
  57. package/dist/services/stellar-service.js +674 -0
  58. package/dist/services/stellar-service.js.map +1 -0
  59. package/dist/soroban/helpers/contract-factory.d.ts +45 -0
  60. package/dist/soroban/helpers/contract-factory.d.ts.map +1 -0
  61. package/dist/soroban/helpers/contract-factory.js +84 -0
  62. package/dist/soroban/helpers/contract-factory.js.map +1 -0
  63. package/dist/soroban/helpers/token-contract-wrapper.d.ts +104 -0
  64. package/dist/soroban/helpers/token-contract-wrapper.d.ts.map +1 -0
  65. package/dist/soroban/helpers/token-contract-wrapper.js +286 -0
  66. package/dist/soroban/helpers/token-contract-wrapper.js.map +1 -0
  67. package/dist/soroban/index.d.ts +19 -0
  68. package/dist/soroban/index.d.ts.map +1 -0
  69. package/dist/soroban/index.js +19 -0
  70. package/dist/soroban/index.js.map +1 -0
  71. package/dist/soroban/soroban-contract-manager.d.ts +71 -0
  72. package/dist/soroban/soroban-contract-manager.d.ts.map +1 -0
  73. package/dist/soroban/soroban-contract-manager.js +376 -0
  74. package/dist/soroban/soroban-contract-manager.js.map +1 -0
  75. package/dist/soroban/types/contract-types.d.ts +156 -0
  76. package/dist/soroban/types/contract-types.d.ts.map +1 -0
  77. package/dist/soroban/types/contract-types.js +3 -0
  78. package/dist/soroban/types/contract-types.js.map +1 -0
  79. package/dist/soroban/utils/abi-parser.d.ts +90 -0
  80. package/dist/soroban/utils/abi-parser.d.ts.map +1 -0
  81. package/dist/soroban/utils/abi-parser.js +308 -0
  82. package/dist/soroban/utils/abi-parser.js.map +1 -0
  83. package/dist/soroban/utils/error-parser.d.ts +70 -0
  84. package/dist/soroban/utils/error-parser.d.ts.map +1 -0
  85. package/dist/soroban/utils/error-parser.js +302 -0
  86. package/dist/soroban/utils/error-parser.js.map +1 -0
  87. package/dist/soroban/utils/event-decoder.d.ts +91 -0
  88. package/dist/soroban/utils/event-decoder.d.ts.map +1 -0
  89. package/dist/soroban/utils/event-decoder.js +307 -0
  90. package/dist/soroban/utils/event-decoder.js.map +1 -0
  91. package/dist/soroban/utils/event-monitor.d.ts +93 -0
  92. package/dist/soroban/utils/event-monitor.d.ts.map +1 -0
  93. package/dist/soroban/utils/event-monitor.js +282 -0
  94. package/dist/soroban/utils/event-monitor.js.map +1 -0
  95. package/dist/soroban/utils/function-signature-builder.d.ts +98 -0
  96. package/dist/soroban/utils/function-signature-builder.d.ts.map +1 -0
  97. package/dist/soroban/utils/function-signature-builder.js +272 -0
  98. package/dist/soroban/utils/function-signature-builder.js.map +1 -0
  99. package/dist/soroban/utils/scval-converter.d.ts +48 -0
  100. package/dist/soroban/utils/scval-converter.d.ts.map +1 -0
  101. package/dist/soroban/utils/scval-converter.js +320 -0
  102. package/dist/soroban/utils/scval-converter.js.map +1 -0
  103. package/dist/sponsored-reserves/builders/sponsored-account-builder.d.ts +58 -0
  104. package/dist/sponsored-reserves/builders/sponsored-account-builder.d.ts.map +1 -0
  105. package/dist/sponsored-reserves/builders/sponsored-account-builder.js +159 -0
  106. package/dist/sponsored-reserves/builders/sponsored-account-builder.js.map +1 -0
  107. package/dist/sponsored-reserves/builders/sponsored-claimable-balance-builder.d.ts +104 -0
  108. package/dist/sponsored-reserves/builders/sponsored-claimable-balance-builder.d.ts.map +1 -0
  109. package/dist/sponsored-reserves/builders/sponsored-claimable-balance-builder.js +258 -0
  110. package/dist/sponsored-reserves/builders/sponsored-claimable-balance-builder.js.map +1 -0
  111. package/dist/sponsored-reserves/builders/sponsored-data-entry-builder.d.ts +96 -0
  112. package/dist/sponsored-reserves/builders/sponsored-data-entry-builder.d.ts.map +1 -0
  113. package/dist/sponsored-reserves/builders/sponsored-data-entry-builder.js +320 -0
  114. package/dist/sponsored-reserves/builders/sponsored-data-entry-builder.js.map +1 -0
  115. package/dist/sponsored-reserves/builders/sponsored-signer-builder.d.ts +100 -0
  116. package/dist/sponsored-reserves/builders/sponsored-signer-builder.d.ts.map +1 -0
  117. package/dist/sponsored-reserves/builders/sponsored-signer-builder.js +271 -0
  118. package/dist/sponsored-reserves/builders/sponsored-signer-builder.js.map +1 -0
  119. package/dist/sponsored-reserves/builders/sponsored-trustline-builder.d.ts +87 -0
  120. package/dist/sponsored-reserves/builders/sponsored-trustline-builder.d.ts.map +1 -0
  121. package/dist/sponsored-reserves/builders/sponsored-trustline-builder.js +281 -0
  122. package/dist/sponsored-reserves/builders/sponsored-trustline-builder.js.map +1 -0
  123. package/dist/sponsored-reserves/index.d.ts +20 -0
  124. package/dist/sponsored-reserves/index.d.ts.map +1 -0
  125. package/dist/sponsored-reserves/index.js +24 -0
  126. package/dist/sponsored-reserves/index.js.map +1 -0
  127. package/dist/sponsored-reserves/services/sponsored-reserves-manager.d.ts +144 -0
  128. package/dist/sponsored-reserves/services/sponsored-reserves-manager.d.ts.map +1 -0
  129. package/dist/sponsored-reserves/services/sponsored-reserves-manager.js +536 -0
  130. package/dist/sponsored-reserves/services/sponsored-reserves-manager.js.map +1 -0
  131. package/dist/sponsored-reserves/templates/claimable-balance-template.d.ts +96 -0
  132. package/dist/sponsored-reserves/templates/claimable-balance-template.d.ts.map +1 -0
  133. package/dist/sponsored-reserves/templates/claimable-balance-template.js +306 -0
  134. package/dist/sponsored-reserves/templates/claimable-balance-template.js.map +1 -0
  135. package/dist/sponsored-reserves/templates/multi-operation-template.d.ts +99 -0
  136. package/dist/sponsored-reserves/templates/multi-operation-template.d.ts.map +1 -0
  137. package/dist/sponsored-reserves/templates/multi-operation-template.js +313 -0
  138. package/dist/sponsored-reserves/templates/multi-operation-template.js.map +1 -0
  139. package/dist/sponsored-reserves/templates/user-onboarding-template.d.ts +79 -0
  140. package/dist/sponsored-reserves/templates/user-onboarding-template.d.ts.map +1 -0
  141. package/dist/sponsored-reserves/templates/user-onboarding-template.js +262 -0
  142. package/dist/sponsored-reserves/templates/user-onboarding-template.js.map +1 -0
  143. package/dist/sponsored-reserves/types/sponsored-reserves-types.d.ts +364 -0
  144. package/dist/sponsored-reserves/types/sponsored-reserves-types.d.ts.map +1 -0
  145. package/dist/sponsored-reserves/types/sponsored-reserves-types.js +9 -0
  146. package/dist/sponsored-reserves/types/sponsored-reserves-types.js.map +1 -0
  147. package/dist/sponsored-reserves/utils/cost-calculator.d.ts +98 -0
  148. package/dist/sponsored-reserves/utils/cost-calculator.d.ts.map +1 -0
  149. package/dist/sponsored-reserves/utils/cost-calculator.js +238 -0
  150. package/dist/sponsored-reserves/utils/cost-calculator.js.map +1 -0
  151. package/dist/sponsored-reserves/utils/sponsorship-validation.d.ts +112 -0
  152. package/dist/sponsored-reserves/utils/sponsorship-validation.d.ts.map +1 -0
  153. package/dist/sponsored-reserves/utils/sponsorship-validation.js +394 -0
  154. package/dist/sponsored-reserves/utils/sponsorship-validation.js.map +1 -0
  155. package/dist/types/stellar-sdk-compat.d.ts +25 -0
  156. package/dist/types/stellar-sdk-compat.d.ts.map +1 -0
  157. package/dist/types/stellar-sdk-compat.js +44 -0
  158. package/dist/types/stellar-sdk-compat.js.map +1 -0
  159. package/dist/types/stellar-types.d.ts +160 -0
  160. package/dist/types/stellar-types.d.ts.map +1 -0
  161. package/dist/types/stellar-types.js +9 -0
  162. package/dist/types/stellar-types.js.map +1 -0
  163. package/dist/utils/encryption.utils.d.ts +9 -0
  164. package/dist/utils/encryption.utils.d.ts.map +1 -0
  165. package/dist/utils/encryption.utils.js +44 -0
  166. package/dist/utils/encryption.utils.js.map +1 -0
  167. package/dist/utils/network-utils.d.ts +138 -0
  168. package/dist/utils/network-utils.d.ts.map +1 -0
  169. package/dist/utils/network-utils.js +240 -0
  170. package/dist/utils/network-utils.js.map +1 -0
  171. package/dist/utils/stellar-utils.d.ts +114 -0
  172. package/dist/utils/stellar-utils.d.ts.map +1 -0
  173. package/dist/utils/stellar-utils.js +186 -0
  174. package/dist/utils/stellar-utils.js.map +1 -0
  175. package/dist/utils/supabase-client.d.ts +2 -0
  176. package/dist/utils/supabase-client.d.ts.map +1 -0
  177. package/dist/utils/supabase-client.js +9 -0
  178. package/dist/utils/supabase-client.js.map +1 -0
  179. package/package.json +60 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Galaxy DevKit
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,576 @@
1
+ # @galaxy/core/stellar-sdk
2
+
3
+
4
+ Enhanced Stellar SDK for Galaxy DevKit with comprehensive support for Stellar operations including claimable balances and liquidity pools.
5
+
6
+ ## Features
7
+
8
+ - ✅ Wallet creation and management
9
+ - ✅ Account operations (balance, info, history)
10
+ - ✅ Payments and transactions
11
+ - ✅ Trustline management
12
+ - ✅ Claimable balances
13
+ - ✅ Liquidity pool operations (AMM)
14
+ - ✅ Network switching (testnet/mainnet)
15
+ - ✅ React hooks support
16
+
17
+
18
+ A comprehensive TypeScript SDK for Stellar blockchain operations, providing high-level abstractions over the Stellar SDK for common operations including account management, payments, assets, and sponsored reserves.
19
+
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ npm install @galaxy/core/stellar-sdk
25
+ ```
26
+
27
+ ## Features
28
+
29
+ - **Account Management**: Create, fund, and manage Stellar accounts
30
+ - **Payments**: Send XLM and custom assets with ease
31
+ - **Asset Operations**: Create trustlines, issue assets, manage balances
32
+ - **Transaction Building**: Simplified transaction construction and submission
33
+ - **Sponsored Reserves**: Enable users to hold assets without XLM reserves
34
+ - **Network Support**: Testnet and Mainnet configuration
35
+
36
+ ## Quick Start
37
+
38
+ ```typescript
39
+ import { StellarService, NetworkConfig } from '@galaxy/core/stellar-sdk';
40
+
41
+ // Configure for testnet
42
+ const config: NetworkConfig = {
43
+ network: 'testnet',
44
+ horizonUrl: 'https://horizon-testnet.stellar.org',
45
+ passphrase: 'Test SDF Network ; September 2015',
46
+ };
47
+
48
+ // Initialize the service
49
+ const stellar = new StellarService(config);
50
+
51
+ // Create a new account
52
+ const keypair = Keypair.random();
53
+ await stellar.createAccount(keypair.publicKey(), '100');
54
+ ```
55
+
56
+ ## Sponsored Reserves
57
+
58
+ The sponsored reserves module enables sponsor accounts to pay base reserves for another account's ledger entries. This is essential for user onboarding without requiring new users to hold XLM.
59
+
60
+ ### Key Concepts
61
+
62
+ - **Sponsor**: Account that pays the reserve requirements
63
+ - **Sponsored**: Account that benefits from the sponsorship
64
+ - **Base Reserve**: Currently 0.5 XLM per ledger entry
65
+ - **Supported Entries**: Accounts, trustlines, offers, data entries, claimable balances, signers
66
+
67
+ ### Basic Usage
68
+
69
+ #### Create a Sponsored Account
70
+
71
+ ```typescript
72
+ import {
73
+ SponsoredAccountBuilder,
74
+ calculateEntryReserve,
75
+ } from '@galaxy/core/stellar-sdk';
76
+ import { Keypair } from '@stellar/stellar-sdk';
77
+
78
+ const networkConfig = {
79
+ network: 'testnet' as const,
80
+ horizonUrl: 'https://horizon-testnet.stellar.org',
81
+ passphrase: 'Test SDF Network ; September 2015',
82
+ };
83
+
84
+ const sponsorKeypair = Keypair.fromSecret('SPONSOR_SECRET');
85
+ const newUserKeypair = Keypair.random();
86
+
87
+ // Calculate cost
88
+ const cost = calculateEntryReserve('account', 1);
89
+ console.log('Sponsorship cost:', cost, 'XLM');
90
+
91
+ // Create sponsored account
92
+ const builder = new SponsoredAccountBuilder(networkConfig);
93
+ const result = await builder.createSponsoredAccount(
94
+ sponsorKeypair.secret(),
95
+ newUserKeypair.secret(),
96
+ '0' // Starting balance can be 0 when sponsored
97
+ );
98
+
99
+ console.log('Account created:', result.hash);
100
+ ```
101
+
102
+ #### Create Sponsored Trustlines
103
+
104
+ ```typescript
105
+ import {
106
+ SponsoredTrustlineBuilder,
107
+ getDetailedBreakdown,
108
+ } from '@galaxy/core/stellar-sdk';
109
+
110
+ const assets = [
111
+ { assetCode: 'USDC', assetIssuer: 'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5' },
112
+ { assetCode: 'EURC', assetIssuer: 'GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2' },
113
+ ];
114
+
115
+ // Calculate cost
116
+ const breakdown = getDetailedBreakdown([{ type: 'trustline', count: assets.length }]);
117
+ console.log('Total cost:', breakdown.totalCost, 'XLM');
118
+
119
+ // Create sponsored trustlines
120
+ const builder = new SponsoredTrustlineBuilder(networkConfig);
121
+ const result = await builder.createMultipleSponsoredTrustlines(
122
+ sponsorKeypair.secret(),
123
+ userKeypair.secret(),
124
+ assets
125
+ );
126
+
127
+ console.log('Trustlines created:', result.sponsoredEntries.length);
128
+ ```
129
+
130
+ #### User Onboarding Template
131
+
132
+ For complete user onboarding (account + trustlines + data entries):
133
+
134
+ ```typescript
135
+ import {
136
+ UserOnboardingTemplate,
137
+ calculateOnboardingCost,
138
+ SponsoredReservesManager,
139
+ } from '@galaxy/core/stellar-sdk';
140
+
141
+ const onboardingConfig = {
142
+ sponsorPublicKey: sponsorKeypair.publicKey(),
143
+ newUserPublicKey: newUserKeypair.publicKey(),
144
+ startingBalance: '0',
145
+ trustlines: [
146
+ { assetCode: 'USDC', assetIssuer: 'GBBD47IF...' },
147
+ { assetCode: 'PLATFORM', assetIssuer: 'GPLATFORM...' },
148
+ ],
149
+ dataEntries: [
150
+ { name: 'onboarded_at', value: new Date().toISOString() },
151
+ { name: 'platform', value: 'galaxy-devkit' },
152
+ ],
153
+ memo: 'Welcome to Galaxy!',
154
+ };
155
+
156
+ // Calculate cost
157
+ const cost = calculateOnboardingCost(onboardingConfig);
158
+ console.log('Total onboarding cost:', cost.totalCost, 'XLM');
159
+
160
+ // Check sponsor eligibility
161
+ const manager = new SponsoredReservesManager(networkConfig);
162
+ const eligibility = await manager.checkSponsorshipEligibility(
163
+ sponsorKeypair.publicKey(),
164
+ cost
165
+ );
166
+
167
+ if (!eligibility.eligible) {
168
+ console.error('Sponsor needs more XLM:', eligibility.shortfall);
169
+ return;
170
+ }
171
+
172
+ // Execute onboarding
173
+ const template = new UserOnboardingTemplate(networkConfig);
174
+ const result = await template.onboardUser(
175
+ onboardingConfig,
176
+ sponsorKeypair.secret(),
177
+ newUserKeypair.secret()
178
+ );
179
+
180
+ console.log('User onboarded:', result.hash);
181
+ ```
182
+
183
+ #### Claimable Balances for Airdrops
184
+
185
+ Create sponsored claimable balances for token airdrops:
186
+
187
+ ```typescript
188
+ import { ClaimableBalanceTemplate } from '@galaxy/core/stellar-sdk';
189
+
190
+ const recipients = [
191
+ { destination: 'GUSER1...', amount: '100' },
192
+ { destination: 'GUSER2...', amount: '100' },
193
+ { destination: 'GUSER3...', amount: '100' },
194
+ ];
195
+
196
+ const asset = { code: 'PLATFORM', issuer: 'GPLATFORM...' };
197
+ const expirationTime = Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60; // 30 days
198
+
199
+ const template = new ClaimableBalanceTemplate(networkConfig);
200
+ const results = await template.createSponsoredAirdrop(
201
+ sponsorKeypair.secret(),
202
+ sourceKeypair.secret(),
203
+ asset,
204
+ recipients,
205
+ expirationTime
206
+ );
207
+
208
+ console.log('Airdrop created:', results.length, 'batches');
209
+ ```
210
+
211
+ #### Vesting Schedules
212
+
213
+ Create time-locked token vesting:
214
+
215
+ ```typescript
216
+ import { ClaimableBalanceTemplate } from '@galaxy/core/stellar-sdk';
217
+
218
+ // Create 4-tranche vesting over 1 year
219
+ const vestingSchedule = ClaimableBalanceTemplate.createLinearVestingSchedule(
220
+ '10000', // Total tokens
221
+ 4, // Number of tranches
222
+ Math.floor(Date.now() / 1000) + 90 * 24 * 60 * 60, // Start in 90 days
223
+ 90 * 24 * 60 * 60 // 90 days between tranches
224
+ );
225
+
226
+ const template = new ClaimableBalanceTemplate(networkConfig);
227
+ const result = await template.createSponsoredVesting(
228
+ sponsorKeypair.secret(),
229
+ sourceKeypair.secret(),
230
+ asset,
231
+ recipientPublicKey,
232
+ vestingSchedule
233
+ );
234
+
235
+ console.log('Vesting created:', result.sponsoredEntries.length, 'tranches');
236
+ ```
237
+
238
+ ### Query Sponsored Entries
239
+
240
+ ```typescript
241
+ import { SponsoredReservesManager } from '@galaxy/core/stellar-sdk';
242
+
243
+ const manager = new SponsoredReservesManager(networkConfig);
244
+
245
+ // Get entries sponsored FOR an account
246
+ const entriesFor = await manager.getSponsoredEntries(userPublicKey);
247
+
248
+ // Get entries sponsored BY an account
249
+ const entriesBy = await manager.getEntriesSponsoredBy(sponsorPublicKey);
250
+
251
+ // Filter by type
252
+ const trustlines = await manager.getSponsoredEntries(userPublicKey, {
253
+ entryType: 'trustline',
254
+ });
255
+ ```
256
+
257
+ ### Revoking Sponsorship
258
+
259
+ ```typescript
260
+ const manager = new SponsoredReservesManager(networkConfig);
261
+
262
+ // Revoke account sponsorship
263
+ await manager.revokeAccountSponsorship(
264
+ sponsorKeypair.secret(),
265
+ accountPublicKey
266
+ );
267
+
268
+ // Revoke trustline sponsorship
269
+ await manager.revokeTrustlineSponsorship(
270
+ sponsorKeypair.secret(),
271
+ accountPublicKey,
272
+ { code: 'USDC', issuer: 'GBBD47IF...' }
273
+ );
274
+ ```
275
+
276
+
277
+ ## Liquidity Pool Operations
278
+
279
+ Liquidity pools enable automated market making (AMM) on Stellar using the constant product formula (x * y = k). Provide liquidity to pools and earn fees from trades.
280
+
281
+ ### Finding Pools
282
+
283
+ ```typescript
284
+ import { Asset } from '@galaxy/core-stellar-sdk';
285
+
286
+ // Find pools for asset pair
287
+ const xlm = Asset.native();
288
+ const usdc = new Asset('USDC', 'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5');
289
+
290
+ const pools = await service.getPoolsForAssets(xlm, usdc, 5);
291
+ console.log('Found', pools.length, 'pools');
292
+
293
+ // Get specific pool details
294
+ const pool = await service.getLiquidityPool(poolId);
295
+ console.log('Reserve A:', pool.reserveA);
296
+ console.log('Reserve B:', pool.reserveB);
297
+ console.log('Total Shares:', pool.totalShares);
298
+ ```
299
+
300
+ ### Depositing Liquidity
301
+
302
+ ```typescript
303
+ // Estimate deposit first
304
+ const estimate = await service.estimatePoolDeposit(
305
+ poolId,
306
+ '100.0000000', // Amount of asset A
307
+ '500.0000000' // Amount of asset B
308
+ );
309
+
310
+ console.log('Expected shares:', estimate.shares);
311
+ console.log('Price impact:', estimate.priceImpact, '%');
312
+ console.log('Pool share:', estimate.poolShare, '%');
313
+
314
+ // Deposit with slippage protection
315
+ const depositResult = await service.depositLiquidity(wallet, {
316
+ poolId: poolId,
317
+ maxAmountA: '100.0000000',
318
+ maxAmountB: '500.0000000',
319
+ slippageTolerance: '0.01', // 1% slippage tolerance
320
+ memo: 'LP deposit'
321
+ }, password);
322
+
323
+ console.log('Transaction Hash:', depositResult.hash);
324
+ ```
325
+
326
+ ### Withdrawing Liquidity
327
+
328
+ ```typescript
329
+ // Get your shares
330
+ const userShares = await service.getLiquidityPoolShares(wallet.publicKey, poolId);
331
+ console.log('Your shares:', userShares);
332
+
333
+ // Estimate withdrawal
334
+ const withdrawEstimate = await service.estimatePoolWithdraw(
335
+ poolId,
336
+ '10.0000000' // Shares to withdraw
337
+ );
338
+
339
+ console.log('Expected Asset A:', withdrawEstimate.amountA);
340
+ console.log('Expected Asset B:', withdrawEstimate.amountB);
341
+
342
+ // Withdraw with slippage protection
343
+ const withdrawResult = await service.withdrawLiquidity(wallet, {
344
+ poolId: poolId,
345
+ shares: '10.0000000',
346
+ slippageTolerance: '0.01',
347
+ memo: 'LP withdrawal'
348
+ }, password);
349
+ ```
350
+
351
+ ### Pool Analytics
352
+
353
+ ```typescript
354
+ import {
355
+ calculateShareValue,
356
+ calculateImpermanentLoss,
357
+ formatPoolAssets,
358
+ calculateSpotPrice
359
+ } from '@galaxy/core-stellar-sdk';
360
+
361
+ // Get pool analytics
362
+ const analytics = await service.getPoolAnalytics(poolId);
363
+ console.log('TVL:', analytics.tvl);
364
+ console.log('Share Price:', analytics.sharePrice);
365
+
366
+ // Calculate your position value
367
+ const { valueA, valueB } = calculateShareValue(userShares, pool);
368
+ console.log('Your position - Asset A:', valueA);
369
+ console.log('Your position - Asset B:', valueB);
370
+
371
+ // Calculate impermanent loss
372
+ const initialPrice = '5.0000000'; // Price when you entered
373
+ const currentPrice = calculateSpotPrice(pool.reserveA, pool.reserveB);
374
+ const il = calculateImpermanentLoss(initialPrice, currentPrice);
375
+ console.log('Impermanent Loss:', il, '%');
376
+
377
+ // Format pool name
378
+ const poolName = formatPoolAssets(pool);
379
+ console.log('Pool:', poolName); // e.g., "XLM/USDC"
380
+ ```
381
+
382
+ ### Slippage Protection
383
+
384
+ ```typescript
385
+ import { calculateMinimumAmounts, calculatePriceBounds } from '@galaxy/core-stellar-sdk';
386
+
387
+ // Calculate minimum amounts with slippage tolerance
388
+ const { minAmountA, minAmountB } = calculateMinimumAmounts(
389
+ '100.0000000',
390
+ '500.0000000',
391
+ '0.01' // 1% slippage
392
+ );
393
+
394
+ // Calculate price bounds
395
+ const currentPrice = calculateSpotPrice(pool.reserveA, pool.reserveB);
396
+ const { minPrice, maxPrice } = calculatePriceBounds(currentPrice, '0.02'); // 2% tolerance
397
+
398
+ // Deposit with price bounds
399
+ await service.depositLiquidity(wallet, {
400
+ poolId: poolId,
401
+ maxAmountA: '100.0000000',
402
+ maxAmountB: '500.0000000',
403
+ minPrice: minPrice,
404
+ maxPrice: maxPrice,
405
+ memo: 'Price protected deposit'
406
+ }, password);
407
+ ```
408
+
409
+ ### Price Calculation Examples
410
+
411
+ ```typescript
412
+ // Constant product formula: x * y = k
413
+ const k = new BigNumber(pool.reserveA).multipliedBy(pool.reserveB);
414
+
415
+ // Spot price: P = reserveB / reserveA
416
+ const spotPrice = new BigNumber(pool.reserveB).dividedBy(pool.reserveA);
417
+
418
+ // First deposit shares: sqrt(amountA * amountB)
419
+ const shares = Math.sqrt(amountA * amountB);
420
+
421
+ // Subsequent deposit shares: min(amountA/reserveA, amountB/reserveB) * totalShares
422
+ const ratioA = amountA / pool.reserveA;
423
+ const ratioB = amountB / pool.reserveB;
424
+ const ratio = Math.min(ratioA, ratioB);
425
+ const depositShares = ratio * pool.totalShares;
426
+
427
+ // Withdrawal amounts: (shares / totalShares) * reserves
428
+ const withdrawAmountA = (shares / pool.totalShares) * pool.reserveA;
429
+ const withdrawAmountB = (shares / pool.totalShares) * pool.reserveB;
430
+ ```
431
+
432
+ ### Important Notes
433
+
434
+ - **Pool IDs**: 64-character hex strings generated by Stellar network
435
+ - **Precision**: All amounts use 7 decimal places
436
+ - **Slippage**: Default 1%, warn if price impact > 5%
437
+ - **Estimation**: Always estimate before executing operations
438
+ - **First Deposit**: Uses geometric mean (sqrt) for share calculation
439
+ - **Subsequent**: Uses proportional ratio to maintain pool balance
440
+
441
+ ## React Hook Usage
442
+
443
+ ### Cost Calculation
444
+
445
+
446
+ ```typescript
447
+ import {
448
+ calculateEntryReserve,
449
+ getDetailedBreakdown,
450
+ calculateTotalCost,
451
+ } from '@galaxy/core/stellar-sdk';
452
+
453
+ // Single entry cost
454
+ const accountCost = calculateEntryReserve('account', 1); // 1 XLM (2 base reserves)
455
+ const trustlineCost = calculateEntryReserve('trustline', 1); // 0.5 XLM
456
+
457
+ // Detailed breakdown
458
+ const breakdown = getDetailedBreakdown([
459
+ { type: 'account', count: 1 },
460
+ { type: 'trustline', count: 3 },
461
+ { type: 'data', count: 2 },
462
+ ]);
463
+
464
+ console.log('Breakdown:');
465
+ for (const item of breakdown.entries) {
466
+ console.log(` ${item.description}: ${item.cost} XLM`);
467
+ }
468
+ console.log('Total:', breakdown.totalCost, 'XLM');
469
+ console.log('Transaction fee:', breakdown.transactionFee, 'XLM');
470
+ ```
471
+
472
+ ### Multi-Signature Support
473
+
474
+ For scenarios where keys are held by different parties:
475
+
476
+ ```typescript
477
+ import { SponsoredAccountBuilder } from '@galaxy/core/stellar-sdk';
478
+
479
+ const builder = new SponsoredAccountBuilder(networkConfig);
480
+
481
+ // Build unsigned transaction
482
+ const { xdr, requiredSigners } = await builder.buildUnsignedTransaction(
483
+ sponsorPublicKey,
484
+ newUserPublicKey,
485
+ '0'
486
+ );
487
+
488
+ console.log('Transaction XDR:', xdr);
489
+ console.log('Required signers:', requiredSigners);
490
+
491
+ // Each party signs the XDR separately
492
+ // Then submit using signAndSubmitSponsorshipTransaction
493
+ ```
494
+
495
+ ## API Reference
496
+
497
+ ### Classes
498
+
499
+ | Class | Description |
500
+ |-------|-------------|
501
+ | `StellarService` | Core service for Stellar operations |
502
+ | `SponsoredReservesManager` | Main manager for sponsored reserves operations |
503
+ | `SponsoredAccountBuilder` | Builder for sponsored account creation |
504
+ | `SponsoredTrustlineBuilder` | Builder for sponsored trustlines |
505
+ | `SponsoredClaimableBalanceBuilder` | Builder for sponsored claimable balances |
506
+ | `SponsoredSignerBuilder` | Builder for sponsored signers |
507
+ | `SponsoredDataEntryBuilder` | Builder for sponsored data entries |
508
+ | `UserOnboardingTemplate` | Template for complete user onboarding |
509
+ | `ClaimableBalanceTemplate` | Template for airdrops and vesting |
510
+ | `MultiOperationTemplate` | Template for batch operations |
511
+
512
+ ### Utility Functions
513
+
514
+ | Function | Description |
515
+ |----------|-------------|
516
+ | `calculateEntryReserve(type, count)` | Calculate reserve for entry type |
517
+ | `getDetailedBreakdown(entries)` | Get detailed cost breakdown |
518
+ | `calculateTotalCost(config)` | Calculate total sponsorship cost |
519
+ | `calculateOnboardingCost(config)` | Calculate user onboarding cost |
520
+ | `validatePublicKey(key)` | Validate Stellar public key |
521
+ | `validateSecretKey(key)` | Validate Stellar secret key |
522
+ | `validateSponsorBalance(sponsor, required)` | Check sponsor has sufficient balance |
523
+
524
+ ### Types
525
+
526
+ ```typescript
527
+ interface NetworkConfig {
528
+ network: 'testnet' | 'mainnet';
529
+ horizonUrl: string;
530
+ passphrase: string;
531
+ }
532
+
533
+ type SponsoredEntryType =
534
+ | 'account'
535
+ | 'trustline'
536
+ | 'offer'
537
+ | 'data'
538
+ | 'claimableBalance'
539
+ | 'signer';
540
+
541
+ interface SponsorshipResult {
542
+ hash: string;
543
+ ledger: number;
544
+ status: 'success' | 'failed';
545
+ feePaid: string;
546
+ sponsoredEntries: SponsoredEntry[];
547
+ }
548
+
549
+ interface UserOnboardingConfig {
550
+ sponsorPublicKey: string;
551
+ newUserPublicKey: string;
552
+ startingBalance: string;
553
+ trustlines?: Array<{ assetCode: string; assetIssuer: string }>;
554
+ dataEntries?: Array<{ name: string; value: string }>;
555
+ memo?: string;
556
+ }
557
+ ```
558
+
559
+ ## Examples
560
+
561
+ See the [examples directory](../../docs/examples/stellar-sdk/) for complete working examples:
562
+
563
+ - `15-sponsor-account.ts` - Create sponsored accounts
564
+ - `16-sponsor-trustline.ts` - Create sponsored trustlines
565
+ - `17-onboarding-flow.ts` - Complete user onboarding flow
566
+
567
+ ## Testing
568
+
569
+ ```bash
570
+ cd packages/core/stellar-sdk
571
+ npm test
572
+ ```
573
+
574
+ ## License
575
+
576
+ MIT License - see the [LICENSE](../../../LICENSE) file for details.
@@ -0,0 +1,99 @@
1
+ /**
2
+ * @fileoverview Claimable Balance Manager
3
+ * @description Manages creation, claiming, and querying of claimable balances
4
+ * @author Galaxy DevKit Team
5
+ * @version 1.0.0
6
+ * @since 2024-12-01
7
+ */
8
+ import { Asset, Horizon } from '@stellar/stellar-sdk';
9
+ import { ClaimableBalance, CreateClaimableBalanceParams, ClaimBalanceParams, QueryClaimableBalancesParams, ClaimableBalanceResult } from './types';
10
+ import { Wallet } from '../types/stellar-types';
11
+ /**
12
+ * Claimable Balance Manager class
13
+ * @class ClaimableBalanceManager
14
+ * @description Handles all claimable balance operations
15
+ */
16
+ export declare class ClaimableBalanceManager {
17
+ private server;
18
+ private networkPassphrase;
19
+ private networkUtils;
20
+ constructor(server: Horizon.Server, networkPassphrase: string);
21
+ /**
22
+ * Creates a claimable balance
23
+ * @param wallet - Source wallet
24
+ * @param params - Create claimable balance parameters
25
+ * @param password - Wallet password
26
+ * @returns Promise<ClaimableBalanceResult>
27
+ */
28
+ createClaimableBalance(wallet: Wallet, params: CreateClaimableBalanceParams, password: string): Promise<ClaimableBalanceResult>;
29
+ /**
30
+ * Claims a claimable balance
31
+ * @param wallet - Claimant wallet
32
+ * @param params - Claim parameters
33
+ * @param password - Wallet password
34
+ * @returns Promise<ClaimableBalanceResult>
35
+ */
36
+ claimBalance(wallet: Wallet, params: ClaimBalanceParams, password: string): Promise<ClaimableBalanceResult>;
37
+ /**
38
+ * Gets claimable balance details by ID
39
+ * @param balanceId - Balance ID
40
+ * @returns Promise<ClaimableBalance>
41
+ */
42
+ getBalanceDetails(balanceId: string): Promise<ClaimableBalance>;
43
+ /**
44
+ * Queries claimable balances
45
+ * @param params - Query parameters
46
+ * @returns Promise<ClaimableBalance[]>
47
+ */
48
+ getClaimableBalances(params?: QueryClaimableBalancesParams): Promise<ClaimableBalance[]>;
49
+ /**
50
+ * Gets claimable balances for a specific account (as claimant)
51
+ * @param publicKey - Account public key
52
+ * @param limit - Number of results to return
53
+ * @returns Promise<ClaimableBalance[]>
54
+ */
55
+ getClaimableBalancesForAccount(publicKey: string, limit?: number): Promise<ClaimableBalance[]>;
56
+ /**
57
+ * Gets claimable balances by asset
58
+ * @param asset - Asset to filter by
59
+ * @param limit - Number of results to return
60
+ * @returns Promise<ClaimableBalance[]>
61
+ */
62
+ getClaimableBalancesByAsset(asset: Asset, limit?: number): Promise<ClaimableBalance[]>;
63
+ /**
64
+ * Validates create claimable balance parameters
65
+ * @param params - Parameters to validate
66
+ * @throws Error if invalid
67
+ */
68
+ private validateCreateParams;
69
+ /**
70
+ * Validates balance ID format
71
+ * @param balanceId - Balance ID to validate
72
+ * @returns boolean
73
+ */
74
+ private isValidBalanceId;
75
+ /**
76
+ * Extracts balance ID from transaction result
77
+ * @param result - Transaction result
78
+ * @returns Promise<Balance ID>
79
+ */
80
+ private extractBalanceId;
81
+ /**
82
+ * Maps Horizon API balance to our ClaimableBalance type
83
+ * @param horizonBalance - Horizon API balance
84
+ * @returns ClaimableBalance
85
+ */
86
+ private mapHorizonBalanceToClaimableBalance;
87
+ /**
88
+ * Maps Horizon predicate to our ClaimPredicate type
89
+ * @param horizonPredicate - Horizon predicate
90
+ * @returns ClaimPredicate
91
+ */
92
+ private mapHorizonPredicateToPredicate;
93
+ /**
94
+ * Estimates transaction fee
95
+ * @returns Promise<string>
96
+ */
97
+ private estimateFee;
98
+ }
99
+ //# sourceMappingURL=claimable-balance-manager.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"claimable-balance-manager.d.ts","sourceRoot":"","sources":["../../src/claimable-balances/claimable-balance-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAEL,KAAK,EAGL,OAAO,EAGR,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,gBAAgB,EAEhB,4BAA4B,EAC5B,kBAAkB,EAClB,4BAA4B,EAC5B,sBAAsB,EACvB,MAAM,SAAS,CAAC;AAKjB,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAIhD;;;;GAIG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,YAAY,CAAe;gBAEvB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM;IAM7D;;;;;;OAMG;IACG,sBAAsB,CAC1B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,4BAA4B,EACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,sBAAsB,CAAC;IAkElC;;;;;;OAMG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,sBAAsB,CAAC;IAwDlC;;;;OAIG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsBrE;;;;OAIG;IACG,oBAAoB,CACxB,MAAM,GAAE,4BAAiC,GACxC,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA+C9B;;;;;OAKG;IACG,8BAA8B,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAW9B;;;;;OAKG;IACG,2BAA2B,CAC/B,KAAK,EAAE,KAAK,EACZ,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAO9B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IA6B5B;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;OAIG;YACW,gBAAgB;IAgC9B;;;;OAIG;IACH,OAAO,CAAC,mCAAmC;IA2B3C;;;;OAIG;IACH,OAAO,CAAC,8BAA8B;IAyCtC;;;OAGG;YACW,WAAW;CAQ1B"}