@0xkoaj/sdk 0.0.1-beta.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.
- package/README.md +821 -0
- package/package.json +60 -0
package/README.md
ADDED
|
@@ -0,0 +1,821 @@
|
|
|
1
|
+
# Web3 SDK
|
|
2
|
+
|
|
3
|
+
A comprehensive TypeScript SDK for interacting with the different contracts and accounts accross multiple networks.
|
|
4
|
+
|
|
5
|
+
## ๐งช Installation
|
|
6
|
+
|
|
7
|
+
### Yarn
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
yarn add @nchamo/sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
### NPM
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @nchamo/sdk
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Quick Start
|
|
20
|
+
|
|
21
|
+
### ๐ท๐ฝโโ๏ธ Building the SDK
|
|
22
|
+
|
|
23
|
+
```typescript
|
|
24
|
+
import { buildSDK } from "@nchamo/sdk";
|
|
25
|
+
|
|
26
|
+
const sdk = buildSDK(config);
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### โ๏ธ Getting Balance for Multiple Tokens
|
|
30
|
+
|
|
31
|
+
```typescript
|
|
32
|
+
const accountBalances = await sdk.balanceService.getBalancesForTokens({
|
|
33
|
+
account: "0x000000000000000000000000000000000000dead",
|
|
34
|
+
tokens: {
|
|
35
|
+
[Chains.ETHEREUM.chainId]: [
|
|
36
|
+
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
|
|
37
|
+
"0x6b175474e89094c44da98b954eedeac495271d0f", // DAI
|
|
38
|
+
],
|
|
39
|
+
[Chains.OPTIMISM.chainId]: [
|
|
40
|
+
"0x7f5c764cbc14f9669b88837ca1490cca17c31607", // USDC
|
|
41
|
+
"0xda10009cbd5d07dd0cecc66161fc93d7c9000da1", // DAI
|
|
42
|
+
],
|
|
43
|
+
},
|
|
44
|
+
config: {
|
|
45
|
+
timeout: "30s",
|
|
46
|
+
},
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### ๐ธ Getting Allowances
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
const accountAllowances = await sdk.allowanceService.getAllowances({
|
|
54
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
55
|
+
token: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
|
|
56
|
+
owner: "0x000000000000000000000000000000000000dead",
|
|
57
|
+
spenders: ["0x6666666600000000000000000000000000009999"],
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### ๐ Getting Trade Quotes
|
|
62
|
+
|
|
63
|
+
```typescript
|
|
64
|
+
const allQuotes = await sdk.quoteService.getAllQuotesWithTxs({
|
|
65
|
+
request: {
|
|
66
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
67
|
+
sellToken: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
|
|
68
|
+
buyToken: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
|
|
69
|
+
order: {
|
|
70
|
+
type: "sell",
|
|
71
|
+
sellAmount: utils.parseUnits("1000", 6), // 1000 USDC
|
|
72
|
+
},
|
|
73
|
+
slippagePercentage: 1,
|
|
74
|
+
takerAddress: signer.address,
|
|
75
|
+
gasSpeed: {
|
|
76
|
+
speed: "instant",
|
|
77
|
+
},
|
|
78
|
+
},
|
|
79
|
+
config: {
|
|
80
|
+
sort: {
|
|
81
|
+
by: "most-swapped-accounting-for-gas",
|
|
82
|
+
},
|
|
83
|
+
},
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Overview
|
|
88
|
+
|
|
89
|
+
The Web3 SDK provides efficient tools to manage token balances, retrieve trade quotes from DEX aggregators, and check token holdings across multiple chains. It's designed to be modular, with each functionality organized into specialized services that handle specific aspects of blockchain interaction.
|
|
90
|
+
|
|
91
|
+
### Available Services
|
|
92
|
+
|
|
93
|
+
The SDK is divided into the following services:
|
|
94
|
+
|
|
95
|
+
- **[Allowances Service](#allowances-service)**: Manage token approvals and permissions across different chains
|
|
96
|
+
- **[Balances Service](#balances-service)**: Query token balances across multiple chains and tokens
|
|
97
|
+
- **[Quotes Service](#quotes-service)**: Get optimized swap quotes from various DEX aggregators
|
|
98
|
+
- **[Gas Service](#gas-service)**: Optimize transaction costs and estimate gas prices
|
|
99
|
+
- **[Prices Service](#prices-service)**: Retrieve token price information across multiple chains
|
|
100
|
+
- **[Metadata Service](#metadata-service)**: Access token metadata and information
|
|
101
|
+
|
|
102
|
+
Each service provides a focused set of functionality while maintaining a consistent interface and error handling approach. This modular design allows developers to use only the services they need while ensuring a cohesive experience across the entire SDK.
|
|
103
|
+
|
|
104
|
+
## Services
|
|
105
|
+
|
|
106
|
+
### Allowances Service
|
|
107
|
+
|
|
108
|
+
The Allowances Service provides functionality to check and manage token allowances across different chains.
|
|
109
|
+
|
|
110
|
+
#### Objective and Potential
|
|
111
|
+
|
|
112
|
+
- **Objective**: Enable efficient management of token approvals across multiple chains and protocols
|
|
113
|
+
- **Potential Use Cases**:
|
|
114
|
+
- Batch checking multiple token approvals in a single call
|
|
115
|
+
- Optimizing gas costs by checking approvals before transactions
|
|
116
|
+
- Managing permissions for DeFi protocols and dApps
|
|
117
|
+
- Cross-chain allowance monitoring and management
|
|
118
|
+
|
|
119
|
+
#### Methods
|
|
120
|
+
|
|
121
|
+
##### `supportedChains()`
|
|
122
|
+
|
|
123
|
+
Returns an array of chain IDs that are supported by the service.
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
const chains = sdk.allowanceService.supportedChains();
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
##### `getAllowanceInChain(params)`
|
|
130
|
+
|
|
131
|
+
Gets the allowance for a specific token and spender on a given chain.
|
|
132
|
+
|
|
133
|
+
```typescript
|
|
134
|
+
const allowance = await sdk.allowanceService.getAllowanceInChain({
|
|
135
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
136
|
+
token: "0x...", // Token address
|
|
137
|
+
owner: "0x...", // Owner address
|
|
138
|
+
spender: "0x...", // Spender address
|
|
139
|
+
config: { timeout: TimeString },
|
|
140
|
+
});
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
##### `getAllowancesInChain(params)`
|
|
144
|
+
|
|
145
|
+
Gets multiple allowances in a single call for a specific chain.
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
const allowances = await sdk.allowanceService.getAllowancesInChain({
|
|
149
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
150
|
+
allowances: [
|
|
151
|
+
{ token: "0x...", owner: "0x...", spender: "0x..." },
|
|
152
|
+
{ token: "0x...", owner: "0x...", spender: "0x..." },
|
|
153
|
+
],
|
|
154
|
+
config: { timeout: TimeString },
|
|
155
|
+
});
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
##### `getAllowances(params)`
|
|
159
|
+
|
|
160
|
+
Gets allowances across multiple chains in a single call.
|
|
161
|
+
|
|
162
|
+
```typescript
|
|
163
|
+
const allowances = await sdk.allowanceService.getAllowances({
|
|
164
|
+
allowances: [
|
|
165
|
+
{
|
|
166
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
167
|
+
token: "0x...",
|
|
168
|
+
owner: "0x...",
|
|
169
|
+
spender: "0x...",
|
|
170
|
+
},
|
|
171
|
+
{
|
|
172
|
+
chainId: Chains.OPTIMISM.chainId,
|
|
173
|
+
token: "0x...",
|
|
174
|
+
owner: "0x...",
|
|
175
|
+
spender: "0x...",
|
|
176
|
+
},
|
|
177
|
+
],
|
|
178
|
+
config: { timeout: TimeString },
|
|
179
|
+
});
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Balances Service
|
|
183
|
+
|
|
184
|
+
The Balances Service allows querying token balances across multiple chains and tokens.
|
|
185
|
+
|
|
186
|
+
#### Objective and Potential
|
|
187
|
+
|
|
188
|
+
- **Objective**: Provide a unified interface for retrieving token balances across multiple chains
|
|
189
|
+
- **Potential Use Cases**:
|
|
190
|
+
- Portfolio tracking across multiple chains
|
|
191
|
+
- Balance monitoring for DeFi positions
|
|
192
|
+
- Multi-chain wallet integration
|
|
193
|
+
- Automated balance checks for trading strategies
|
|
194
|
+
|
|
195
|
+
#### Methods
|
|
196
|
+
|
|
197
|
+
##### `supportedChains()`
|
|
198
|
+
|
|
199
|
+
Returns an array of chain IDs that are supported by the service.
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
const chains = sdk.balanceService.supportedChains();
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
##### `getBalancesForAccountInChain(params)`
|
|
206
|
+
|
|
207
|
+
Gets balances for a specific account in a single chain.
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
const balances = await sdk.balanceService.getBalancesForAccountInChain({
|
|
211
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
212
|
+
account: "0x...",
|
|
213
|
+
tokens: ["0x...", "0x..."],
|
|
214
|
+
config: { timeout: "30s" },
|
|
215
|
+
});
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
##### `getBalancesForAccount(params)`
|
|
219
|
+
|
|
220
|
+
Gets balances for a specific account across multiple chains.
|
|
221
|
+
|
|
222
|
+
```typescript
|
|
223
|
+
const balances = await sdk.balanceService.getBalancesForAccount({
|
|
224
|
+
account: "0x...",
|
|
225
|
+
tokens: [
|
|
226
|
+
{ chainId: Chains.ETHEREUM.chainId, token: "0x..." },
|
|
227
|
+
{ chainId: Chains.OPTIMISM.chainId, token: "0x..." },
|
|
228
|
+
],
|
|
229
|
+
config: { timeout: "30s" },
|
|
230
|
+
});
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
##### `getBalancesInChain(params)`
|
|
234
|
+
|
|
235
|
+
Gets balances for multiple accounts in a single chain.
|
|
236
|
+
|
|
237
|
+
```typescript
|
|
238
|
+
const balances = await sdk.balanceService.getBalancesInChain({
|
|
239
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
240
|
+
tokens: [
|
|
241
|
+
{ account: "0x...", token: "0x..." },
|
|
242
|
+
{ account: "0x...", token: "0x..." },
|
|
243
|
+
],
|
|
244
|
+
config: { timeout: "30s" },
|
|
245
|
+
});
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
##### `getBalances(params)`
|
|
249
|
+
|
|
250
|
+
Gets balances for multiple accounts across multiple chains.
|
|
251
|
+
|
|
252
|
+
```typescript
|
|
253
|
+
const balances = await sdk.balanceService.getBalances({
|
|
254
|
+
tokens: [
|
|
255
|
+
{ chainId: Chains.ETHEREUM.chainId, account: "0x...", token: "0x..." },
|
|
256
|
+
{ chainId: Chains.OPTIMISM.chainId, account: "0x...", token: "0x..." },
|
|
257
|
+
],
|
|
258
|
+
config: { timeout: "30s" },
|
|
259
|
+
});
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
### Quotes Service
|
|
263
|
+
|
|
264
|
+
The Quotes Service provides comprehensive functionality for getting trade quotes from various DEX aggregators.
|
|
265
|
+
|
|
266
|
+
#### Objective and Potential
|
|
267
|
+
|
|
268
|
+
- **Objective**: Aggregate and optimize trade quotes from multiple DEX sources
|
|
269
|
+
- **Potential Use Cases**:
|
|
270
|
+
- Finding the best trade routes across multiple DEXs
|
|
271
|
+
- Gas-optimized trading strategies
|
|
272
|
+
- Cross-chain arbitrage opportunities
|
|
273
|
+
- Automated trading systems
|
|
274
|
+
- Price impact analysis
|
|
275
|
+
|
|
276
|
+
#### Methods
|
|
277
|
+
|
|
278
|
+
##### `supportedSources()`
|
|
279
|
+
|
|
280
|
+
Returns metadata about all supported quote sources.
|
|
281
|
+
|
|
282
|
+
```typescript
|
|
283
|
+
const sources = sdk.quoteService.supportedSources();
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
##### `supportedChains()`
|
|
287
|
+
|
|
288
|
+
Returns an array of chain IDs that are supported by the service.
|
|
289
|
+
|
|
290
|
+
```typescript
|
|
291
|
+
const chains = sdk.quoteService.supportedChains();
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
##### `supportedSourcesInChain(params)`
|
|
295
|
+
|
|
296
|
+
Returns metadata about quote sources supported in a specific chain.
|
|
297
|
+
|
|
298
|
+
```typescript
|
|
299
|
+
const sources = sdk.quoteService.supportedSourcesInChain({
|
|
300
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
301
|
+
});
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
##### `supportedGasSpeeds()`
|
|
305
|
+
|
|
306
|
+
Returns supported gas speeds for each chain.
|
|
307
|
+
|
|
308
|
+
```typescript
|
|
309
|
+
const gasSpeeds = sdk.quoteService.supportedGasSpeeds();
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
##### `estimateQuotes(params)`
|
|
313
|
+
|
|
314
|
+
Gets estimated quotes from all sources without transaction details.
|
|
315
|
+
|
|
316
|
+
```typescript
|
|
317
|
+
const quotes = sdk.quoteService.estimateQuotes({
|
|
318
|
+
request: {
|
|
319
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
320
|
+
sellToken: "0x...",
|
|
321
|
+
buyToken: "0x...",
|
|
322
|
+
order: { type: "sell", sellAmount: BigInt("1000000") },
|
|
323
|
+
slippagePercentage: 1,
|
|
324
|
+
},
|
|
325
|
+
config: { timeout: TimeString },
|
|
326
|
+
});
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
##### `estimateAllQuotes(params)`
|
|
330
|
+
|
|
331
|
+
Gets estimated quotes from all sources and returns them in a sorted array.
|
|
332
|
+
|
|
333
|
+
```typescript
|
|
334
|
+
const quotes = await sdk.quoteService.estimateAllQuotes({
|
|
335
|
+
request: {
|
|
336
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
337
|
+
sellToken: "0x...",
|
|
338
|
+
buyToken: "0x...",
|
|
339
|
+
order: { type: "sell", sellAmount: BigInt("1000000") },
|
|
340
|
+
slippagePercentage: 1,
|
|
341
|
+
},
|
|
342
|
+
config: {
|
|
343
|
+
ignoredFailed: boolean,
|
|
344
|
+
sort: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
|
|
345
|
+
timeout: TimeString,
|
|
346
|
+
},
|
|
347
|
+
});
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
##### `getQuotes(params)`
|
|
351
|
+
|
|
352
|
+
Gets quotes from all sources with transaction details.
|
|
353
|
+
|
|
354
|
+
```typescript
|
|
355
|
+
const quotes = sdk.quoteService.getQuotes({
|
|
356
|
+
request: {
|
|
357
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
358
|
+
sellToken: "0x...",
|
|
359
|
+
buyToken: "0x...",
|
|
360
|
+
order: { type: "sell", sellAmount: BigInt("1000000") },
|
|
361
|
+
slippagePercentage: 1,
|
|
362
|
+
takerAddress: "0x...",
|
|
363
|
+
},
|
|
364
|
+
config: { timeout: TimeString },
|
|
365
|
+
});
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
##### `getAllQuotes(params)`
|
|
369
|
+
|
|
370
|
+
Gets quotes from all sources and returns them in a sorted array.
|
|
371
|
+
|
|
372
|
+
```typescript
|
|
373
|
+
const quotes = await sdk.quoteService.getAllQuotes({
|
|
374
|
+
request: {
|
|
375
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
376
|
+
sellToken: "0x...",
|
|
377
|
+
buyToken: "0x...",
|
|
378
|
+
order: { type: "sell", sellAmount: BigInt("1000000") },
|
|
379
|
+
slippagePercentage: 1,
|
|
380
|
+
takerAddress: "0x...",
|
|
381
|
+
},
|
|
382
|
+
config: {
|
|
383
|
+
ignoredFailed: boolean,
|
|
384
|
+
sort: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
|
|
385
|
+
timeout: TimeString,
|
|
386
|
+
},
|
|
387
|
+
});
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
##### `getBestQuote(params)`
|
|
391
|
+
|
|
392
|
+
Gets the best quote according to specified criteria.
|
|
393
|
+
|
|
394
|
+
```typescript
|
|
395
|
+
const bestQuote = await sdk.quoteService.getBestQuote({
|
|
396
|
+
request: {
|
|
397
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
398
|
+
sellToken: "0x...",
|
|
399
|
+
buyToken: "0x...",
|
|
400
|
+
order: { type: "sell", sellAmount: BigInt("1000000") },
|
|
401
|
+
slippagePercentage: 1,
|
|
402
|
+
takerAddress: "0x...",
|
|
403
|
+
},
|
|
404
|
+
config: {
|
|
405
|
+
choose: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
|
|
406
|
+
timeout: TimeString,
|
|
407
|
+
},
|
|
408
|
+
});
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
##### `getAllQuotesWithTxs(params)`
|
|
412
|
+
|
|
413
|
+
Gets quotes with built transactions from all sources.
|
|
414
|
+
|
|
415
|
+
```typescript
|
|
416
|
+
const quotesWithTxs = await sdk.quoteService.getAllQuotesWithTxs({
|
|
417
|
+
request: {
|
|
418
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
419
|
+
sellToken: "0x...",
|
|
420
|
+
buyToken: "0x...",
|
|
421
|
+
order: { type: "sell", sellAmount: BigInt("1000000") },
|
|
422
|
+
slippagePercentage: 1,
|
|
423
|
+
takerAddress: "0x...",
|
|
424
|
+
},
|
|
425
|
+
config: {
|
|
426
|
+
ignoredFailed: boolean,
|
|
427
|
+
sort: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
|
|
428
|
+
timeout: TimeString,
|
|
429
|
+
},
|
|
430
|
+
});
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
##### `buildTxs(params)`
|
|
434
|
+
|
|
435
|
+
Builds transactions for given quotes.
|
|
436
|
+
|
|
437
|
+
```typescript
|
|
438
|
+
const txs = sdk.quoteService.buildTxs({
|
|
439
|
+
quotes: quotes,
|
|
440
|
+
sourceConfig: SourceConfig,
|
|
441
|
+
config: { timeout: TimeString },
|
|
442
|
+
});
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
##### `buildAllTxs(params)`
|
|
446
|
+
|
|
447
|
+
Builds transactions for all quotes and returns them in a sorted array.
|
|
448
|
+
|
|
449
|
+
```typescript
|
|
450
|
+
const allTxs = await sdk.quoteService.buildAllTxs({
|
|
451
|
+
quotes: quotes,
|
|
452
|
+
sourceConfig: SourceConfig,
|
|
453
|
+
config: {
|
|
454
|
+
timeout: TimeString,
|
|
455
|
+
ignoredFailed: boolean,
|
|
456
|
+
},
|
|
457
|
+
});
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
### Gas Service
|
|
461
|
+
|
|
462
|
+
The Gas Service provides gas price estimation and optimization across different chains.
|
|
463
|
+
|
|
464
|
+
#### Objective and Potential
|
|
465
|
+
|
|
466
|
+
- **Objective**: Optimize transaction costs across different chains and networks
|
|
467
|
+
- **Potential Use Cases**:
|
|
468
|
+
- Gas price monitoring and optimization
|
|
469
|
+
- Transaction cost estimation
|
|
470
|
+
- Gas-aware trading strategies
|
|
471
|
+
- Multi-chain gas price comparison
|
|
472
|
+
- Automated gas price optimization
|
|
473
|
+
|
|
474
|
+
#### Methods
|
|
475
|
+
|
|
476
|
+
##### `supportedChains()`
|
|
477
|
+
|
|
478
|
+
Returns an array of chain IDs that are supported by the service.
|
|
479
|
+
|
|
480
|
+
```typescript
|
|
481
|
+
const chains = sdk.gasService.supportedChains();
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
##### `supportedSpeeds()`
|
|
485
|
+
|
|
486
|
+
Returns supported gas speeds for each chain.
|
|
487
|
+
|
|
488
|
+
```typescript
|
|
489
|
+
const speeds = sdk.gasService.supportedSpeeds();
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
##### `estimateGas(params)`
|
|
493
|
+
|
|
494
|
+
Estimates gas usage for a transaction.
|
|
495
|
+
|
|
496
|
+
```typescript
|
|
497
|
+
const gasEstimation = await sdk.gasService.estimateGas({
|
|
498
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
499
|
+
tx: {
|
|
500
|
+
from: "0x...",
|
|
501
|
+
to: "0x...",
|
|
502
|
+
data: "0x...",
|
|
503
|
+
},
|
|
504
|
+
config: { timeout: TimeString },
|
|
505
|
+
});
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
##### `getGasPrice(params)`
|
|
509
|
+
|
|
510
|
+
Gets gas prices for different speeds on a chain.
|
|
511
|
+
|
|
512
|
+
```typescript
|
|
513
|
+
const gasPrices = await sdk.gasService.getGasPrice({
|
|
514
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
515
|
+
config: {
|
|
516
|
+
timeout: TimeString,
|
|
517
|
+
fields: {
|
|
518
|
+
standard: "required" | "best effort" | "can ignore",
|
|
519
|
+
fast: "required" | "best effort" | "can ignore",
|
|
520
|
+
instant: "required" | "best effort" | "can ignore",
|
|
521
|
+
},
|
|
522
|
+
},
|
|
523
|
+
});
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
##### `calculateGasCost(params)`
|
|
527
|
+
|
|
528
|
+
Calculates gas cost for a transaction.
|
|
529
|
+
|
|
530
|
+
```typescript
|
|
531
|
+
const gasCost = await sdk.gasService.calculateGasCost({
|
|
532
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
533
|
+
gasEstimation: BigInt("21000"),
|
|
534
|
+
tx: {
|
|
535
|
+
from: "0x...",
|
|
536
|
+
to: "0x...",
|
|
537
|
+
data: "0x...",
|
|
538
|
+
},
|
|
539
|
+
config: {
|
|
540
|
+
timeout: TimeString,
|
|
541
|
+
fields: {
|
|
542
|
+
standard: "required" | "best effort" | "can ignore",
|
|
543
|
+
fast: "required" | "best effort" | "can ignore",
|
|
544
|
+
instant: "required" | "best effort" | "can ignore",
|
|
545
|
+
},
|
|
546
|
+
},
|
|
547
|
+
});
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
##### `getQuickGasCalculator(params)`
|
|
551
|
+
|
|
552
|
+
Gets a quick gas calculator for a specific chain.
|
|
553
|
+
|
|
554
|
+
```typescript
|
|
555
|
+
const calculator = await sdk.gasService.getQuickGasCalculator({
|
|
556
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
557
|
+
config: {
|
|
558
|
+
timeout: TimeString,
|
|
559
|
+
fields: {
|
|
560
|
+
standard: "required" | "best effort" | "can ignore",
|
|
561
|
+
fast: "required" | "best effort" | "can ignore",
|
|
562
|
+
instant: "required" | "best effort" | "can ignore",
|
|
563
|
+
},
|
|
564
|
+
},
|
|
565
|
+
});
|
|
566
|
+
|
|
567
|
+
// Use the calculator
|
|
568
|
+
const gasPrices = calculator.getGasPrice();
|
|
569
|
+
const gasCost = calculator.calculateGasCost({
|
|
570
|
+
gasEstimation: BigInt("21000"),
|
|
571
|
+
tx: {
|
|
572
|
+
from: "0x...",
|
|
573
|
+
to: "0x...",
|
|
574
|
+
data: "0x...",
|
|
575
|
+
},
|
|
576
|
+
});
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
### Prices Service
|
|
580
|
+
|
|
581
|
+
The Prices Service provides token price information across multiple chains.
|
|
582
|
+
|
|
583
|
+
#### Objective and Potential
|
|
584
|
+
|
|
585
|
+
- **Objective**: Provide a unified interface for retrieving token prices across multiple chains
|
|
586
|
+
- **Potential Use Cases**:
|
|
587
|
+
- Price feeds for DeFi applications
|
|
588
|
+
- Token value calculations
|
|
589
|
+
- Historical price analysis
|
|
590
|
+
- Price chart generation
|
|
591
|
+
- Multi-chain price aggregation
|
|
592
|
+
|
|
593
|
+
#### Methods
|
|
594
|
+
|
|
595
|
+
##### `supportedChains()`
|
|
596
|
+
|
|
597
|
+
Returns an array of chain IDs that are supported by the service.
|
|
598
|
+
|
|
599
|
+
```typescript
|
|
600
|
+
const chains = sdk.pricesService.supportedChains();
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
##### `supportedQueries()`
|
|
604
|
+
|
|
605
|
+
Returns the supported price queries for each chain.
|
|
606
|
+
|
|
607
|
+
```typescript
|
|
608
|
+
const queries = sdk.pricesService.supportedQueries();
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
##### `getCurrentPricesInChain(params)`
|
|
612
|
+
|
|
613
|
+
Gets current prices for tokens in a specific chain.
|
|
614
|
+
|
|
615
|
+
```typescript
|
|
616
|
+
const prices = await sdk.pricesService.getCurrentPricesInChain({
|
|
617
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
618
|
+
tokens: ["0x...", "0x..."],
|
|
619
|
+
config: { timeout: "30s" },
|
|
620
|
+
});
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
##### `getCurrentPrices(params)`
|
|
624
|
+
|
|
625
|
+
Gets current prices for tokens across multiple chains.
|
|
626
|
+
|
|
627
|
+
```typescript
|
|
628
|
+
const prices = await sdk.pricesService.getCurrentPrices({
|
|
629
|
+
tokens: [
|
|
630
|
+
{ chainId: Chains.ETHEREUM.chainId, token: "0x..." },
|
|
631
|
+
{ chainId: Chains.OPTIMISM.chainId, token: "0x..." },
|
|
632
|
+
],
|
|
633
|
+
config: { timeout: "30s" },
|
|
634
|
+
});
|
|
635
|
+
```
|
|
636
|
+
|
|
637
|
+
##### `getHistoricalPricesInChain(params)`
|
|
638
|
+
|
|
639
|
+
Gets historical prices for tokens in a specific chain at a given timestamp.
|
|
640
|
+
|
|
641
|
+
```typescript
|
|
642
|
+
const prices = await sdk.pricesService.getHistoricalPricesInChain({
|
|
643
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
644
|
+
tokens: ["0x...", "0x..."],
|
|
645
|
+
timestamp: 1234567890,
|
|
646
|
+
searchWidth: "1h",
|
|
647
|
+
config: { timeout: "30s" },
|
|
648
|
+
});
|
|
649
|
+
```
|
|
650
|
+
|
|
651
|
+
##### `getHistoricalPrices(params)`
|
|
652
|
+
|
|
653
|
+
Gets historical prices for tokens across multiple chains at a given timestamp.
|
|
654
|
+
|
|
655
|
+
```typescript
|
|
656
|
+
const prices = await sdk.pricesService.getHistoricalPrices({
|
|
657
|
+
tokens: [
|
|
658
|
+
{ chainId: Chains.ETHEREUM.chainId, token: "0x..." },
|
|
659
|
+
{ chainId: Chains.OPTIMISM.chainId, token: "0x..." },
|
|
660
|
+
],
|
|
661
|
+
timestamp: 1234567890,
|
|
662
|
+
searchWidth: "1h",
|
|
663
|
+
config: { timeout: "30s" },
|
|
664
|
+
});
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
##### `getBulkHistoricalPrices(params)`
|
|
668
|
+
|
|
669
|
+
Gets historical prices for multiple tokens at different timestamps.
|
|
670
|
+
|
|
671
|
+
```typescript
|
|
672
|
+
const prices = await sdk.pricesService.getBulkHistoricalPrices({
|
|
673
|
+
tokens: [
|
|
674
|
+
{ chainId: Chains.ETHEREUM.chainId, token: "0x...", timestamp: 1234567890 },
|
|
675
|
+
{ chainId: Chains.OPTIMISM.chainId, token: "0x...", timestamp: 1234567890 },
|
|
676
|
+
],
|
|
677
|
+
searchWidth: "1h",
|
|
678
|
+
config: { timeout: "30s" },
|
|
679
|
+
});
|
|
680
|
+
```
|
|
681
|
+
|
|
682
|
+
##### `getChart(params)`
|
|
683
|
+
|
|
684
|
+
Gets price chart data for tokens over a specified time period.
|
|
685
|
+
|
|
686
|
+
```typescript
|
|
687
|
+
const chart = await sdk.pricesService.getChart({
|
|
688
|
+
tokens: [
|
|
689
|
+
{ chainId: Chains.ETHEREUM.chainId, token: "0x..." },
|
|
690
|
+
{ chainId: Chains.OPTIMISM.chainId, token: "0x..." },
|
|
691
|
+
],
|
|
692
|
+
span: 100,
|
|
693
|
+
period: "1d",
|
|
694
|
+
bound: { from: 1234567890 },
|
|
695
|
+
searchWidth: "1h",
|
|
696
|
+
});
|
|
697
|
+
```
|
|
698
|
+
|
|
699
|
+
### Metadata Service
|
|
700
|
+
|
|
701
|
+
The Metadata Service provides token metadata information across multiple chains.
|
|
702
|
+
|
|
703
|
+
#### Objective and Potential
|
|
704
|
+
|
|
705
|
+
- **Objective**: Provide a unified interface for retrieving token metadata across multiple chains
|
|
706
|
+
- **Potential Use Cases**:
|
|
707
|
+
- Token information display in UIs
|
|
708
|
+
- Token validation and verification
|
|
709
|
+
- Multi-chain token management
|
|
710
|
+
- Token data aggregation
|
|
711
|
+
|
|
712
|
+
#### Methods
|
|
713
|
+
|
|
714
|
+
##### `supportedChains()`
|
|
715
|
+
|
|
716
|
+
Returns an array of chain IDs that are supported by the service.
|
|
717
|
+
|
|
718
|
+
```typescript
|
|
719
|
+
const chains = sdk.metadataService.supportedChains();
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
##### `supportedProperties()`
|
|
723
|
+
|
|
724
|
+
Returns the supported metadata properties for each chain.
|
|
725
|
+
|
|
726
|
+
```typescript
|
|
727
|
+
const properties = sdk.metadataService.supportedProperties();
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
##### `getMetadataInChain(params)`
|
|
731
|
+
|
|
732
|
+
Gets metadata for tokens in a specific chain.
|
|
733
|
+
|
|
734
|
+
```typescript
|
|
735
|
+
const metadata = await sdk.metadataService.getMetadataInChain({
|
|
736
|
+
chainId: Chains.ETHEREUM.chainId,
|
|
737
|
+
tokens: ["0x...", "0x..."],
|
|
738
|
+
config: {
|
|
739
|
+
fields: { symbol: "required", decimals: "required" },
|
|
740
|
+
timeout: "30s",
|
|
741
|
+
},
|
|
742
|
+
});
|
|
743
|
+
```
|
|
744
|
+
|
|
745
|
+
##### `getMetadata(params)`
|
|
746
|
+
|
|
747
|
+
Gets metadata for tokens across multiple chains.
|
|
748
|
+
|
|
749
|
+
```typescript
|
|
750
|
+
const metadata = await sdk.metadataService.getMetadata({
|
|
751
|
+
tokens: [
|
|
752
|
+
{ chainId: Chains.ETHEREUM.chainId, token: "0x..." },
|
|
753
|
+
{ chainId: Chains.OPTIMISM.chainId, token: "0x..." },
|
|
754
|
+
],
|
|
755
|
+
config: {
|
|
756
|
+
fields: { symbol: "required", decimals: "required" },
|
|
757
|
+
timeout: "30s",
|
|
758
|
+
},
|
|
759
|
+
});
|
|
760
|
+
```
|
|
761
|
+
|
|
762
|
+
## Advanced Usage
|
|
763
|
+
|
|
764
|
+
### Error Handling
|
|
765
|
+
|
|
766
|
+
The SDK provides comprehensive error handling for all services:
|
|
767
|
+
|
|
768
|
+
```typescript
|
|
769
|
+
try {
|
|
770
|
+
const quotes = await sdk.quoteService.getAllQuotes({...});
|
|
771
|
+
} catch (error) {
|
|
772
|
+
if (error instanceof FailedToGenerateAnyQuotesError) {
|
|
773
|
+
// Handle quote generation failure
|
|
774
|
+
}
|
|
775
|
+
}
|
|
776
|
+
```
|
|
777
|
+
|
|
778
|
+
### Configuration
|
|
779
|
+
|
|
780
|
+
Each service can be configured with custom timeouts and other parameters:
|
|
781
|
+
|
|
782
|
+
```typescript
|
|
783
|
+
const quotes = await sdk.quoteService.getAllQuotes({
|
|
784
|
+
request: {...},
|
|
785
|
+
config: {
|
|
786
|
+
timeout: "30s",
|
|
787
|
+
ignoredFailed: true,
|
|
788
|
+
sort: {
|
|
789
|
+
by: "most-swapped-accounting-for-gas",
|
|
790
|
+
using: "gas-price"
|
|
791
|
+
}
|
|
792
|
+
}
|
|
793
|
+
});
|
|
794
|
+
```
|
|
795
|
+
|
|
796
|
+
### Multi-chain Support
|
|
797
|
+
|
|
798
|
+
All services support operations across multiple chains:
|
|
799
|
+
|
|
800
|
+
```typescript
|
|
801
|
+
const balances = await sdk.balanceService.getBalancesForTokens({
|
|
802
|
+
account: "0x...",
|
|
803
|
+
tokens: {
|
|
804
|
+
[Chains.ETHEREUM.chainId]: ["0x..."],
|
|
805
|
+
[Chains.OPTIMISM.chainId]: ["0x..."],
|
|
806
|
+
[Chains.ARBITRUM.chainId]: ["0x..."],
|
|
807
|
+
},
|
|
808
|
+
});
|
|
809
|
+
```
|
|
810
|
+
|
|
811
|
+
## ๐จโ๐ป Development
|
|
812
|
+
|
|
813
|
+
### Environment Setup
|
|
814
|
+
|
|
815
|
+
```bash
|
|
816
|
+
yarn install
|
|
817
|
+
```
|
|
818
|
+
|
|
819
|
+
## Contributing
|
|
820
|
+
|
|
821
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
package/package.json
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@0xkoaj/sdk",
|
|
3
|
+
"version": "0.0.1-beta.1",
|
|
4
|
+
"contributors": [],
|
|
5
|
+
"main": "./dist/index.js",
|
|
6
|
+
"files": [
|
|
7
|
+
"dist/**"
|
|
8
|
+
],
|
|
9
|
+
"scripts": {
|
|
10
|
+
"build": "tsc -p tsconfig.json && tsconfig-replace-paths -s src -p tsconfig.json",
|
|
11
|
+
"lint:check": "prettier --check .",
|
|
12
|
+
"lint:fix": "sort-package-json && prettier --write .",
|
|
13
|
+
"prepare": "husky install",
|
|
14
|
+
"script": "ts-node -r tsconfig-paths/register",
|
|
15
|
+
"test": "jest --forceExit --detectOpenHandles --verbose",
|
|
16
|
+
"test:integration": "jest --forceExit --detectOpenHandles --verbose --testPathPattern=test/integration",
|
|
17
|
+
"test:unit": "jest --forceExit --detectOpenHandles --verbose --testPathPattern=test/unit"
|
|
18
|
+
},
|
|
19
|
+
"lint-staged": {
|
|
20
|
+
"*.{js,css,md,ts,sol}": "prettier --write",
|
|
21
|
+
"package.json": "sort-package-json"
|
|
22
|
+
},
|
|
23
|
+
"dependencies": {
|
|
24
|
+
"cross-fetch": "4.1.0",
|
|
25
|
+
"crypto-js": "4.2.0",
|
|
26
|
+
"deepmerge": "4.3.1",
|
|
27
|
+
"lru-cache": "11.1.0",
|
|
28
|
+
"ms": "3.0.0-canary.1",
|
|
29
|
+
"qs": "6.14.0",
|
|
30
|
+
"viem": "2.33.1"
|
|
31
|
+
},
|
|
32
|
+
"devDependencies": {
|
|
33
|
+
"@commitlint/cli": "19.8.1",
|
|
34
|
+
"@commitlint/config-conventional": "19.8.1",
|
|
35
|
+
"@types/chai": "5.2.2",
|
|
36
|
+
"@types/chai-as-promised": "7.1.8",
|
|
37
|
+
"@types/crypto-js": "4.1.2",
|
|
38
|
+
"@types/jest": "29.5.6",
|
|
39
|
+
"@types/node": "24.1.0",
|
|
40
|
+
"@types/qs": "6.14.0",
|
|
41
|
+
"@types/ws": "8.5.10",
|
|
42
|
+
"chai": "4.3.7",
|
|
43
|
+
"chai-as-promised": "7.1.2",
|
|
44
|
+
"dotenv": "16.3.1",
|
|
45
|
+
"husky": "8.0.3",
|
|
46
|
+
"jest": "29.7.0",
|
|
47
|
+
"lint-staged": "13.2.2",
|
|
48
|
+
"patch-package": "8.0.0",
|
|
49
|
+
"prettier": "2.8.8",
|
|
50
|
+
"sort-package-json": "3.4.0",
|
|
51
|
+
"ts-jest": "29.4.0",
|
|
52
|
+
"ts-node": "10.9.1",
|
|
53
|
+
"tsconfig-paths": "4.2.0",
|
|
54
|
+
"tsconfig-replace-paths": "0.0.14",
|
|
55
|
+
"typescript": "5.4.2"
|
|
56
|
+
},
|
|
57
|
+
"publishConfig": {
|
|
58
|
+
"access": "public"
|
|
59
|
+
}
|
|
60
|
+
}
|