@agglayer/sdk 0.1.0-beta.1 → 0.1.0-beta.3
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 +268 -79
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,60 +1,181 @@
|
|
|
1
1
|
# AggLayer SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://opensource.org/licenses/ISC)
|
|
4
|
+
[](https://www.typescriptlang.org/)
|
|
5
|
+
[](https://nodejs.org/)
|
|
6
|
+
[](https://bun.sh/)
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
A comprehensive TypeScript SDK for interacting with AggLayer's ARC API and blockchain operations. Built with modular architecture, type safety, and developer experience in mind.
|
|
9
|
+
|
|
10
|
+
## 🚀 Quick Start
|
|
11
|
+
|
|
12
|
+
### Installation
|
|
6
13
|
|
|
7
14
|
```bash
|
|
8
|
-
|
|
15
|
+
# Install latest stable version
|
|
16
|
+
npm install @agglayer/sdk
|
|
17
|
+
|
|
18
|
+
# Install beta version (for testing)
|
|
19
|
+
npm install @agglayer/sdk@beta
|
|
20
|
+
|
|
21
|
+
# Install alpha version (experimental)
|
|
22
|
+
npm install @agglayer/sdk@alpha
|
|
9
23
|
```
|
|
10
24
|
|
|
11
|
-
|
|
25
|
+
### Basic Usage
|
|
12
26
|
|
|
13
27
|
```typescript
|
|
14
|
-
import { AggLayerSDK } from 'agglayer
|
|
28
|
+
import { AggLayerSDK } from '@agglayer/sdk';
|
|
15
29
|
|
|
30
|
+
// Initialize SDK with default Core module
|
|
16
31
|
const sdk = new AggLayerSDK();
|
|
17
32
|
```
|
|
18
33
|
|
|
19
|
-
##
|
|
34
|
+
## 📋 Release Channels
|
|
20
35
|
|
|
21
|
-
|
|
36
|
+
| Channel | Description | Stability | Usage |
|
|
37
|
+
| -------- | ---------------------------------- | ------------------- | --------------------------------- |
|
|
38
|
+
| `latest` | Stable releases from `main` branch | ✅ Production Ready | `npm install @agglayer/sdk` |
|
|
39
|
+
| `beta` | Prereleases from `develop` branch | ⚠️ Testing | `npm install @agglayer/sdk@beta` |
|
|
40
|
+
| `alpha` | Early development releases | 🚧 Experimental | `npm install @agglayer/sdk@alpha` |
|
|
22
41
|
|
|
23
|
-
|
|
24
|
-
- npm
|
|
42
|
+
## 🏗️ Architecture
|
|
25
43
|
|
|
26
|
-
|
|
44
|
+
The SDK is built with a modular architecture supporting two main modules:
|
|
27
45
|
|
|
28
|
-
|
|
29
|
-
|
|
46
|
+
### Core Module
|
|
47
|
+
|
|
48
|
+
- **ARC API Integration**: Interact with AggLayer's REST API
|
|
49
|
+
- **Chain Metadata**: Retrieve supported chains and tokens
|
|
50
|
+
- **Route Discovery**: Find optimal bridging routes
|
|
51
|
+
- **Transaction Building**: Build complex multi-step transactions
|
|
52
|
+
|
|
53
|
+
### Native Module
|
|
54
|
+
|
|
55
|
+
- **ERC20 Operations**: Token balance, transfers, approvals
|
|
56
|
+
- **Bridge Operations**: Cross-chain bridge interactions
|
|
57
|
+
- **Multi-Chain Support**: Work with multiple blockchain networks
|
|
58
|
+
- **Raw Wei Handling**: All amounts returned as unformatted Wei strings
|
|
59
|
+
|
|
60
|
+
## 📖 Usage Examples
|
|
61
|
+
|
|
62
|
+
### Core Module - API Operations
|
|
63
|
+
|
|
64
|
+
```typescript
|
|
65
|
+
// Get Core client
|
|
66
|
+
const core = sdk.getCore();
|
|
67
|
+
|
|
68
|
+
// Retrieve all supported chains
|
|
69
|
+
const chains = await core.getAllChains();
|
|
70
|
+
console.log('Supported chains:', chains);
|
|
71
|
+
|
|
72
|
+
// Get chain metadata for specific networks
|
|
73
|
+
const chainData = await core.getChainMetadataByChainIds([1, 137, 11155111]);
|
|
74
|
+
console.log('Chain metadata:', chainData);
|
|
75
|
+
|
|
76
|
+
// Find bridging routes
|
|
77
|
+
const routes = await core.getRoutes({
|
|
78
|
+
fromChainId: 1,
|
|
79
|
+
toChainId: 137,
|
|
80
|
+
fromTokenAddress: '0xA0b86a33E6441b8c4C8C0e4b8c4C8C0e4b8c4C8C0',
|
|
81
|
+
toTokenAddress: '0xB0b86a33E6441b8c4C8C0e4b8c4C8C0e4b8c4C8C0',
|
|
82
|
+
amount: '1000000000000000000', // 1 token in wei
|
|
83
|
+
fromAddress: '0x1234567890123456789012345678901234567890',
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
// Build transaction from route steps
|
|
87
|
+
const transaction = await core.buildTransaction({
|
|
88
|
+
steps: routes.steps,
|
|
89
|
+
fromAddress: '0x1234567890123456789012345678901234567890',
|
|
90
|
+
});
|
|
30
91
|
```
|
|
31
92
|
|
|
32
|
-
###
|
|
93
|
+
### Native Module - Blockchain Operations
|
|
94
|
+
|
|
95
|
+
```typescript
|
|
96
|
+
// Get Native client
|
|
97
|
+
const native = sdk.getNative();
|
|
98
|
+
|
|
99
|
+
// Get native token balance
|
|
100
|
+
const nativeBalance = await native.getNativeBalance(
|
|
101
|
+
'0x1234567890123456789012345678901234567890',
|
|
102
|
+
11155111 // Sepolia
|
|
103
|
+
);
|
|
104
|
+
console.log('Native balance (wei):', nativeBalance);
|
|
33
105
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
106
|
+
// Create ERC20 instance
|
|
107
|
+
const erc20 = native.erc20(
|
|
108
|
+
'0x1234567890123456789012345678901234567890', // USDC on Sepolia
|
|
109
|
+
11155111
|
|
110
|
+
);
|
|
111
|
+
|
|
112
|
+
// Get ERC20 token balance
|
|
113
|
+
const tokenBalance = await erc20.getBalance(
|
|
114
|
+
'0xabcdefabcdefabcdefabcdefabcdefabcdefabcd'
|
|
115
|
+
);
|
|
116
|
+
console.log('Token balance (wei):', tokenBalance);
|
|
42
117
|
|
|
43
|
-
|
|
118
|
+
// Build transfer transaction
|
|
119
|
+
const transferTx = await erc20.buildTransfer(
|
|
120
|
+
'0xabcdefabcdefabcdefabcdefabcdefabcdefabcd', // recipient
|
|
121
|
+
'1000000000', // 1000 USDC (6 decimals) in wei
|
|
122
|
+
'0x1111111111111111111111111111111111111111' // from address
|
|
123
|
+
);
|
|
124
|
+
|
|
125
|
+
// Build approval transaction
|
|
126
|
+
const approvalTx = await erc20.buildApprove(
|
|
127
|
+
'0x2222222222222222222222222222222222222222', // spender
|
|
128
|
+
'1000000000', // amount in wei
|
|
129
|
+
'0x1111111111111111111111111111111111111111' // from address
|
|
130
|
+
);
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Bridge Operations
|
|
44
134
|
|
|
45
135
|
```typescript
|
|
46
|
-
|
|
136
|
+
// Create bridge instance
|
|
137
|
+
const bridge = native.bridge(
|
|
138
|
+
'0x3333333333333333333333333333333333333333', // bridge contract
|
|
139
|
+
11155111 // Sepolia
|
|
140
|
+
);
|
|
141
|
+
|
|
142
|
+
// Build bridge transaction
|
|
143
|
+
const bridgeTx = await bridge.buildBridgeTransaction({
|
|
144
|
+
toChainId: 137, // Polygon
|
|
145
|
+
tokenAddress: '0x1234567890123456789012345678901234567890',
|
|
146
|
+
amount: '1000000000',
|
|
147
|
+
recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
|
|
148
|
+
fromAddress: '0x1111111111111111111111111111111111111111',
|
|
149
|
+
});
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## ⚙️ Configuration
|
|
153
|
+
|
|
154
|
+
### SDK Configuration
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
import { AggLayerSDK, SDK_MODES } from '@agglayer/sdk';
|
|
47
158
|
|
|
48
159
|
const sdk = new AggLayerSDK({
|
|
49
|
-
mode: [
|
|
160
|
+
mode: [SDK_MODES.CORE, SDK_MODES.NATIVE], // Enable both modules
|
|
161
|
+
core: {
|
|
162
|
+
apiBaseUrl: 'https://api.agglayer.com',
|
|
163
|
+
apiTimeout: 30000, // 30 seconds
|
|
164
|
+
},
|
|
50
165
|
native: {
|
|
51
|
-
defaultNetwork: 11155111,
|
|
166
|
+
defaultNetwork: 11155111, // Default chain ID
|
|
52
167
|
chains: [
|
|
53
168
|
{
|
|
54
|
-
id:
|
|
55
|
-
name: 'Ethereum
|
|
56
|
-
rpcUrl: 'https://
|
|
57
|
-
nativeCurrency: { name: '
|
|
169
|
+
id: 1,
|
|
170
|
+
name: 'Ethereum Mainnet',
|
|
171
|
+
rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2/your-key',
|
|
172
|
+
nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
|
|
173
|
+
},
|
|
174
|
+
{
|
|
175
|
+
id: 137,
|
|
176
|
+
name: 'Polygon',
|
|
177
|
+
rpcUrl: 'https://polygon-rpc.com',
|
|
178
|
+
nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
|
|
58
179
|
},
|
|
59
180
|
],
|
|
60
181
|
customRpcUrls: {
|
|
@@ -65,72 +186,140 @@ const sdk = new AggLayerSDK({
|
|
|
65
186
|
});
|
|
66
187
|
```
|
|
67
188
|
|
|
68
|
-
###
|
|
189
|
+
### Module-Specific Usage
|
|
69
190
|
|
|
70
191
|
```typescript
|
|
71
|
-
//
|
|
72
|
-
const
|
|
192
|
+
// Core-only configuration
|
|
193
|
+
const coreOnlySdk = new AggLayerSDK({
|
|
194
|
+
mode: [SDK_MODES.CORE],
|
|
195
|
+
core: {
|
|
196
|
+
apiBaseUrl: 'https://api.agglayer.com',
|
|
197
|
+
},
|
|
198
|
+
native: {} as any, // Required but unused
|
|
199
|
+
});
|
|
73
200
|
|
|
74
|
-
//
|
|
75
|
-
const
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
201
|
+
// Native-only configuration
|
|
202
|
+
const nativeOnlySdk = new AggLayerSDK({
|
|
203
|
+
mode: [SDK_MODES.NATIVE],
|
|
204
|
+
core: {} as any, // Required but unused
|
|
205
|
+
native: {
|
|
206
|
+
defaultNetwork: 11155111,
|
|
207
|
+
chains: [
|
|
208
|
+
/* your chains */
|
|
209
|
+
],
|
|
210
|
+
},
|
|
211
|
+
});
|
|
212
|
+
```
|
|
79
213
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
214
|
+
## 🔧 Development
|
|
215
|
+
|
|
216
|
+
### Prerequisites
|
|
217
|
+
|
|
218
|
+
- Node.js 18+
|
|
219
|
+
- npm or bun
|
|
220
|
+
|
|
221
|
+
### Setup
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
# Clone the repository
|
|
225
|
+
git clone https://github.com/agglayer/sdk.git
|
|
226
|
+
cd sdk
|
|
227
|
+
|
|
228
|
+
# Install dependencies
|
|
229
|
+
npm install
|
|
230
|
+
|
|
231
|
+
# Build the project
|
|
232
|
+
npm run build
|
|
85
233
|
```
|
|
86
234
|
|
|
87
|
-
###
|
|
235
|
+
### Available Scripts
|
|
88
236
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
237
|
+
| Script | Description |
|
|
238
|
+
| ----------------------- | ----------------------------------- |
|
|
239
|
+
| `npm run build` | Build the library for production |
|
|
240
|
+
| `npm run dev` | Build in watch mode for development |
|
|
241
|
+
| `npm run test` | Run test suite |
|
|
242
|
+
| `npm run test:coverage` | Run tests with coverage report |
|
|
243
|
+
| `npm run test:watch` | Run tests in watch mode |
|
|
244
|
+
| `npm run lint` | Run ESLint |
|
|
245
|
+
| `npm run lint:fix` | Fix ESLint issues automatically |
|
|
246
|
+
| `npm run format` | Format code with Prettier |
|
|
247
|
+
| `npm run format:check` | Check code formatting |
|
|
248
|
+
| `npm run typecheck` | Type check with TypeScript |
|
|
249
|
+
|
|
250
|
+
### Testing
|
|
95
251
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
252
|
+
```bash
|
|
253
|
+
# Run all tests
|
|
254
|
+
npm run test
|
|
255
|
+
|
|
256
|
+
# Run tests with coverage
|
|
257
|
+
npm run test:coverage
|
|
102
258
|
|
|
103
|
-
|
|
104
|
-
|
|
259
|
+
# Run tests in watch mode
|
|
260
|
+
npm run test:watch
|
|
105
261
|
```
|
|
106
262
|
|
|
107
|
-
## Features
|
|
263
|
+
## 🎯 Key Features
|
|
264
|
+
|
|
265
|
+
### Type Safety
|
|
266
|
+
|
|
267
|
+
- Full TypeScript support with strict configuration
|
|
268
|
+
- Comprehensive type definitions for all operations
|
|
269
|
+
- IntelliSense support for better developer experience
|
|
270
|
+
|
|
271
|
+
### Modular Design
|
|
272
|
+
|
|
273
|
+
- **Core Module**: ARC API integration for route discovery and transaction building
|
|
274
|
+
- **Native Module**: Direct blockchain interactions for ERC20 and bridge operations
|
|
275
|
+
- Flexible configuration allowing module-specific usage
|
|
276
|
+
|
|
277
|
+
### Multi-Chain Support
|
|
278
|
+
|
|
279
|
+
- Built-in support for major EVM chains
|
|
280
|
+
- Custom chain configuration
|
|
281
|
+
- Custom RPC URL support
|
|
282
|
+
- Chain registry for easy network management
|
|
283
|
+
|
|
284
|
+
### Raw Wei Handling
|
|
285
|
+
|
|
286
|
+
- All token amounts returned as unformatted Wei strings
|
|
287
|
+
- No automatic decimal conversion for precision control
|
|
288
|
+
- Consistent number formatting across all operations
|
|
289
|
+
|
|
290
|
+
### Lightweight & Efficient
|
|
291
|
+
|
|
292
|
+
- Minimal dependencies (only viem for blockchain interactions)
|
|
293
|
+
- Tree-shakeable modules
|
|
294
|
+
- Optimized bundle size
|
|
295
|
+
|
|
296
|
+
## 🤝 Contributing
|
|
108
297
|
|
|
109
|
-
|
|
110
|
-
- **Transaction Building**: Build transactions for MetaMask or other wallets
|
|
111
|
-
- **Multi-Chain Support**: Support for multiple blockchain networks
|
|
112
|
-
- **TypeScript**: Full TypeScript support with type safety
|
|
113
|
-
- **Lightweight**: Minimal dependencies, focused on core functionality
|
|
298
|
+
We welcome contributions! Please follow these steps:
|
|
114
299
|
|
|
115
|
-
|
|
300
|
+
1. **Fork the repository**
|
|
301
|
+
2. **Create a feature branch**: `git checkout -b feature/your-feature-name`
|
|
302
|
+
3. **Make your changes** following our coding standards
|
|
303
|
+
4. **Run tests**: `npm run test`
|
|
304
|
+
5. **Run linting**: `npm run lint`
|
|
305
|
+
6. **Format code**: `npm run format`
|
|
306
|
+
7. **Submit a pull request**
|
|
116
307
|
|
|
117
|
-
|
|
308
|
+
### Code Quality Standards
|
|
118
309
|
|
|
119
|
-
- **
|
|
120
|
-
- **
|
|
121
|
-
- **
|
|
122
|
-
- **
|
|
123
|
-
- **
|
|
310
|
+
- **TypeScript**: Strict type checking enabled
|
|
311
|
+
- **ESLint**: Enforced code quality rules
|
|
312
|
+
- **Prettier**: Consistent code formatting
|
|
313
|
+
- **Vitest**: Comprehensive test coverage
|
|
314
|
+
- **Husky**: Pre-commit hooks for quality assurance
|
|
124
315
|
|
|
125
|
-
|
|
316
|
+
## 📄 License
|
|
126
317
|
|
|
127
|
-
|
|
128
|
-
2. Create a feature branch
|
|
129
|
-
3. Make your changes
|
|
130
|
-
4. Run tests: `npm run test`
|
|
131
|
-
5. Run linting: `npm run lint`
|
|
132
|
-
6. Submit a pull request
|
|
318
|
+
ISC License - see [LICENSE](LICENSE) file for details.
|
|
133
319
|
|
|
134
|
-
##
|
|
320
|
+
## 🔗 Links
|
|
135
321
|
|
|
136
|
-
|
|
322
|
+
- [GitHub Repository](https://github.com/agglayer/sdk)
|
|
323
|
+
- [NPM Package](https://www.npmjs.com/package/@agglayer/sdk)
|
|
324
|
+
- [Documentation](https://docs.agglayer.com)
|
|
325
|
+
- [Issues](https://github.com/agglayer/sdk/issues)
|