@cetusprotocol/aggregator-sdk 0.16.0 โ 1.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.
- package/.github/workflows/test.yml +152 -0
- package/.prettierrc +11 -0
- package/.vscode/settings.json +8 -0
- package/CLAUDE.md +101 -0
- package/README.md +122 -4
- package/dist/index.d.mts +783 -241
- package/dist/index.d.ts +783 -241
- package/dist/index.js +5823 -5101
- package/dist/index.mjs +5722 -5096
- package/docs/Cetus_Aggregator_V3_/346/216/245/345/217/243/346/226/207/346/241/243.md +706 -0
- package/docs/REFACTOR.md +24 -0
- package/docs//350/267/257/345/276/204/346/213/223/346/211/221/346/216/222/345/272/217.md +208 -0
- package/package.json +8 -4
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
name: Automated Testing with Success Rate
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [ main, develop, refactor-v3 ]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [ main, develop, refactor-v3 ]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
|
|
13
|
+
steps:
|
|
14
|
+
- name: Checkout code
|
|
15
|
+
uses: actions/checkout@v4
|
|
16
|
+
|
|
17
|
+
- name: Setup Bun
|
|
18
|
+
uses: oven-sh/setup-bun@v1
|
|
19
|
+
with:
|
|
20
|
+
bun-version: latest
|
|
21
|
+
|
|
22
|
+
- name: Install dependencies
|
|
23
|
+
run: bun install
|
|
24
|
+
|
|
25
|
+
- name: Run tests with coverage and statistics
|
|
26
|
+
run: |
|
|
27
|
+
echo "๐งช Running all tests..."
|
|
28
|
+
|
|
29
|
+
# Run tests with JSON output for parsing
|
|
30
|
+
bun test --json --outputFile=test-results.json --coverage || true
|
|
31
|
+
|
|
32
|
+
# Also run regular test output for display
|
|
33
|
+
echo "๐ Test Results:"
|
|
34
|
+
bun test --verbose || TEST_EXIT_CODE=$?
|
|
35
|
+
|
|
36
|
+
# Parse test results and calculate success rate
|
|
37
|
+
echo "๐ Calculating test success rate..."
|
|
38
|
+
|
|
39
|
+
# Create a simple Node.js script to parse JSON results
|
|
40
|
+
cat > calculate-stats.js << 'EOF'
|
|
41
|
+
const fs = require('fs');
|
|
42
|
+
|
|
43
|
+
try {
|
|
44
|
+
// Try to read the JSON results file
|
|
45
|
+
let results;
|
|
46
|
+
if (fs.existsSync('test-results.json')) {
|
|
47
|
+
const data = fs.readFileSync('test-results.json', 'utf8');
|
|
48
|
+
results = JSON.parse(data);
|
|
49
|
+
} else {
|
|
50
|
+
console.log('โ ๏ธ JSON results file not found, using alternative method');
|
|
51
|
+
process.exit(1);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
// Calculate statistics
|
|
55
|
+
const totalTests = results.numTotalTests || 0;
|
|
56
|
+
const passedTests = results.numPassedTests || 0;
|
|
57
|
+
const failedTests = results.numFailedTests || 0;
|
|
58
|
+
const successRate = totalTests > 0 ? ((passedTests / totalTests) * 100).toFixed(2) : 0;
|
|
59
|
+
|
|
60
|
+
console.log('\n๐ =================================');
|
|
61
|
+
console.log('๐ TEST EXECUTION SUMMARY');
|
|
62
|
+
console.log('๐ =================================');
|
|
63
|
+
console.log(`๐ Total Tests: ${totalTests}`);
|
|
64
|
+
console.log(`โ
Passed Tests: ${passedTests}`);
|
|
65
|
+
console.log(`โ Failed Tests: ${failedTests}`);
|
|
66
|
+
console.log(`๐ Success Rate: ${successRate}%`);
|
|
67
|
+
console.log('๐ =================================\n');
|
|
68
|
+
|
|
69
|
+
// Set environment variables for GitHub Actions
|
|
70
|
+
console.log(`::set-output name=total_tests::${totalTests}`);
|
|
71
|
+
console.log(`::set-output name=passed_tests::${passedTests}`);
|
|
72
|
+
console.log(`::set-output name=failed_tests::${failedTests}`);
|
|
73
|
+
console.log(`::set-output name=success_rate::${successRate}`);
|
|
74
|
+
|
|
75
|
+
// Exit with non-zero code if tests failed
|
|
76
|
+
if (failedTests > 0) {
|
|
77
|
+
process.exit(1);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
} catch (error) {
|
|
81
|
+
console.error('Error parsing test results:', error);
|
|
82
|
+
process.exit(1);
|
|
83
|
+
}
|
|
84
|
+
EOF
|
|
85
|
+
|
|
86
|
+
# Run the statistics calculation
|
|
87
|
+
node calculate-stats.js || {
|
|
88
|
+
echo "โ ๏ธ Falling back to alternative statistics calculation..."
|
|
89
|
+
|
|
90
|
+
# Alternative method using grep on test output
|
|
91
|
+
echo "๐ ================================="
|
|
92
|
+
echo "๐ TEST EXECUTION SUMMARY"
|
|
93
|
+
echo "๐ ================================="
|
|
94
|
+
|
|
95
|
+
# Count test files
|
|
96
|
+
TEST_FILES=$(find tests -name "*.test.ts" | wc -l)
|
|
97
|
+
echo "๐ Total Test Files: $TEST_FILES"
|
|
98
|
+
|
|
99
|
+
# Try to get basic stats from bun test output
|
|
100
|
+
echo "๐ Running tests again for statistics..."
|
|
101
|
+
bun test 2>&1 | tee test-output.log
|
|
102
|
+
|
|
103
|
+
# Parse the output for basic statistics
|
|
104
|
+
if grep -q "Tests:" test-output.log; then
|
|
105
|
+
STATS=$(grep "Tests:" test-output.log | tail -1)
|
|
106
|
+
echo "๐ $STATS"
|
|
107
|
+
fi
|
|
108
|
+
|
|
109
|
+
echo "๐ ================================="
|
|
110
|
+
|
|
111
|
+
# Clean up
|
|
112
|
+
rm -f test-output.log
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
# Clean up
|
|
116
|
+
rm -f calculate-stats.js test-results.json
|
|
117
|
+
|
|
118
|
+
# Exit with the original test exit code
|
|
119
|
+
exit ${TEST_EXIT_CODE:-0}
|
|
120
|
+
|
|
121
|
+
- name: Upload test results
|
|
122
|
+
uses: actions/upload-artifact@v3
|
|
123
|
+
if: always()
|
|
124
|
+
with:
|
|
125
|
+
name: test-results
|
|
126
|
+
path: |
|
|
127
|
+
coverage/
|
|
128
|
+
test-results.json
|
|
129
|
+
retention-days: 30
|
|
130
|
+
|
|
131
|
+
- name: Comment PR with test results
|
|
132
|
+
uses: actions/github-script@v6
|
|
133
|
+
if: github.event_name == 'pull_request'
|
|
134
|
+
with:
|
|
135
|
+
script: |
|
|
136
|
+
const output = `## ๐งช Test Results
|
|
137
|
+
|
|
138
|
+
**Test Execution Summary:**
|
|
139
|
+
- Total Tests: \${{ steps.test.outputs.total_tests || 'N/A' }}
|
|
140
|
+
- Passed Tests: \${{ steps.test.outputs.passed_tests || 'N/A' }}
|
|
141
|
+
- Failed Tests: \${{ steps.test.outputs.failed_tests || 'N/A' }}
|
|
142
|
+
- Success Rate: \${{ steps.test.outputs.success_rate || 'N/A' }}%
|
|
143
|
+
|
|
144
|
+
\${{ steps.test.outputs.failed_tests > 0 && 'โ Some tests failed. Please review the test output above.' || 'โ
All tests passed!' }}
|
|
145
|
+
`;
|
|
146
|
+
|
|
147
|
+
github.rest.issues.createComment({
|
|
148
|
+
issue_number: context.issue.number,
|
|
149
|
+
owner: context.repo.owner,
|
|
150
|
+
repo: context.repo.repo,
|
|
151
|
+
body: output
|
|
152
|
+
});
|
package/.prettierrc
ADDED
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
4
|
+
|
|
5
|
+
## Project Overview
|
|
6
|
+
|
|
7
|
+
The **Cetus Aggregator SDK** is a TypeScript library for the Sui blockchain ecosystem that provides swap aggregation across 25+ decentralized exchanges (DEXs). The SDK finds optimal trading routes, best prices, and lowest slippage by integrating multiple DEXs including Cetus, DeepBook, Kriya, FlowX, Turbos, Aftermath, and many others.
|
|
8
|
+
|
|
9
|
+
## Development Commands
|
|
10
|
+
|
|
11
|
+
### Build and Development
|
|
12
|
+
|
|
13
|
+
- `bun run build` - Compile TypeScript to CommonJS/ESM with type definitions using tsup
|
|
14
|
+
- `bun run dev` - Development mode with file watching
|
|
15
|
+
- `bun run clean` - Remove build artifacts and dependencies
|
|
16
|
+
- `bun run publish:test` - Publish experimental version to bun
|
|
17
|
+
|
|
18
|
+
### Testing
|
|
19
|
+
|
|
20
|
+
- `bun test` - Run Jest test suite with ESM support
|
|
21
|
+
- Tests are organized by aggregator versions (v2/v3) in `/tests/` directory
|
|
22
|
+
- Individual DEX tests located in `/tests/aggregatorv2/router/`
|
|
23
|
+
- Mathematical function tests in `/tests/math.test.ts`
|
|
24
|
+
|
|
25
|
+
## Architecture
|
|
26
|
+
|
|
27
|
+
### Core Components
|
|
28
|
+
|
|
29
|
+
**Main Entry Points:**
|
|
30
|
+
|
|
31
|
+
- `src/index.ts` - Main export barrel
|
|
32
|
+
- `src/client.ts` - Aggregator v2 client implementation
|
|
33
|
+
- `src/clientv3.ts` - Aggregator v3 client implementation
|
|
34
|
+
|
|
35
|
+
**Key Directories:**
|
|
36
|
+
|
|
37
|
+
- `src/transaction/` - DEX-specific swap implementations (25+ integrations)
|
|
38
|
+
- `src/utils/` - Utility functions for coins, transactions, API calls
|
|
39
|
+
- `src/types/` - TypeScript type definitions
|
|
40
|
+
- `src/movecall/` - Move contract interaction helpers
|
|
41
|
+
- `src/api/` - API interaction layer
|
|
42
|
+
- `src/math/` - Mathematical calculations for trading
|
|
43
|
+
|
|
44
|
+
### DEX Integration Pattern
|
|
45
|
+
|
|
46
|
+
Each DEX has its own transaction module in `src/transaction/` following a consistent pattern:
|
|
47
|
+
|
|
48
|
+
- Import from main client class (AggregatorClient/AggregatorClient)
|
|
49
|
+
- Implement DEX-specific swap logic
|
|
50
|
+
- Handle transaction building and execution
|
|
51
|
+
- Support both amount-in and amount-out calculations
|
|
52
|
+
|
|
53
|
+
### TypeScript Configuration
|
|
54
|
+
|
|
55
|
+
- Uses path mapping: `~/*` maps to `src/*`
|
|
56
|
+
- Jest configured with same path mapping
|
|
57
|
+
- Targets ES6 with CommonJS modules
|
|
58
|
+
- Strict TypeScript enabled
|
|
59
|
+
|
|
60
|
+
### Key Dependencies
|
|
61
|
+
|
|
62
|
+
- `@mysten/sui@^1.6.0` - Official Sui SDK for blockchain interactions
|
|
63
|
+
- `@pythnetwork/pyth-sui-js@^2.1.0` - Pyth oracle integration for price feeds
|
|
64
|
+
- `bn.js@^5.2.1` - Big number handling for precise calculations
|
|
65
|
+
- `decimal.js@^10.4.3` - Decimal arithmetic for financial calculations
|
|
66
|
+
|
|
67
|
+
### Multi-Version Support
|
|
68
|
+
|
|
69
|
+
The SDK supports both Aggregator v2 and v3 APIs:
|
|
70
|
+
|
|
71
|
+
- v2: Legacy aggregator with extensive DEX support
|
|
72
|
+
- v3: Newer aggregator with enhanced features and performance
|
|
73
|
+
|
|
74
|
+
### Testing Strategy
|
|
75
|
+
|
|
76
|
+
- Unit tests for mathematical functions (`tests/math.test.ts`)
|
|
77
|
+
- Integration tests for each DEX in `tests/aggregatorv2/router/`
|
|
78
|
+
- Router functionality tests (`tests/aggregatorv2/router.test.ts`)
|
|
79
|
+
- Wallet interaction tests (`tests/wallet.test.ts`)
|
|
80
|
+
|
|
81
|
+
### Build Process
|
|
82
|
+
|
|
83
|
+
Uses `tsup` for bundling with:
|
|
84
|
+
|
|
85
|
+
- Multiple output formats (CJS, ESM, TypeScript declarations)
|
|
86
|
+
- Tree shaking enabled
|
|
87
|
+
- Code splitting support
|
|
88
|
+
- Development watch mode
|
|
89
|
+
|
|
90
|
+
### Contract Addresses
|
|
91
|
+
|
|
92
|
+
The SDK works with multiple contract versions on Sui mainnet:
|
|
93
|
+
|
|
94
|
+
- CetusAggregatorV2: `0x3864c7c59a4889fec05d1aae4bc9dba5a0e0940594b424fbed44cb3f6ac4c032`
|
|
95
|
+
- CetusAggregatorV2ExtendV1: `0x39402d188b7231036e52266ebafad14413b4bf3daea4ac17115989444e6cd516`
|
|
96
|
+
- CetusAggregatorV2ExtendV2: `0x368d13376443a8051b22b42a9125f6a3bc836422bb2d9c4a53984b8d6624c326`
|
|
97
|
+
- CetusAggregatorSimple: `0x594d67abc0778023ac852800578271dd7e18698ad06e6298034858c77612333d`
|
|
98
|
+
|
|
99
|
+
### Environment Setup
|
|
100
|
+
|
|
101
|
+
The SDK works with Sui mainnet and testnet environments via the `Env` enum. Configure clients with appropriate RPC endpoints and package configurations for the target network.
|
package/README.md
CHANGED
|
@@ -29,7 +29,123 @@ Multi-Platform Support: Currently, we have integrated multiple mainstream DEXs o
|
|
|
29
29
|
|
|
30
30
|
By using our aggregator, you can trade more efficiently and securely on the Sui blockchain, fully leveraging the various opportunities brought by decentralized finance (DeFi).
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
## Supported Providers
|
|
33
|
+
|
|
34
|
+
The Cetus Aggregator SDK supports 25+ decentralized exchanges (DEXs) on the Sui blockchain:
|
|
35
|
+
|
|
36
|
+
- **Cetus**
|
|
37
|
+
- **DeepBook V3**
|
|
38
|
+
- **Kriya V2/V3**
|
|
39
|
+
- **FlowX V2/V3**
|
|
40
|
+
- **Turbos**
|
|
41
|
+
- **Aftermath**
|
|
42
|
+
- **Haedal**
|
|
43
|
+
- **Volo**
|
|
44
|
+
- **AfSui**
|
|
45
|
+
- **Bluemove**
|
|
46
|
+
- **Scallop**
|
|
47
|
+
- **Suilend**
|
|
48
|
+
- **Bluefin**
|
|
49
|
+
- **HaedalHMM**
|
|
50
|
+
- **Alphafi**
|
|
51
|
+
- **SpringSui**
|
|
52
|
+
- **Steamm CPMM**
|
|
53
|
+
- **Steamm OMM**
|
|
54
|
+
- **Metastable**
|
|
55
|
+
- **Obric**
|
|
56
|
+
- **HaWAL**
|
|
57
|
+
- **Momentum**
|
|
58
|
+
- **Magma**
|
|
59
|
+
- **Sevenk**
|
|
60
|
+
|
|
61
|
+
# Aggregator SDK V3
|
|
62
|
+
|
|
63
|
+
## Advantages of Aggregator Client V3
|
|
64
|
+
|
|
65
|
+
The new Aggregator Client V3 offers significant improvements over the previous version:
|
|
66
|
+
|
|
67
|
+
### Transaction Traceability
|
|
68
|
+
|
|
69
|
+
- **Complete Transaction History**: All swap transactions are fully traceable on the blockchain
|
|
70
|
+
- **Detailed Route Information**: Track exactly which DEXs and pools were used in multi-hop swaps
|
|
71
|
+
- **Gas Optimization Transparency**: See how transactions were optimized to reduce gas costs
|
|
72
|
+
|
|
73
|
+
### Transaction Merging for Gas Optimization
|
|
74
|
+
|
|
75
|
+
- **Reduced Gas Costs**: Significantly lower transaction fees through optimized execution paths
|
|
76
|
+
- **Smart Route Aggregation**: Automatically combines similar operations to minimize gas usage
|
|
77
|
+
|
|
78
|
+
### Enhanced Features
|
|
79
|
+
|
|
80
|
+
- **Increased Reliability**: More robust transaction execution with better error handling
|
|
81
|
+
|
|
82
|
+
## Migration from Aggregator Client to V3
|
|
83
|
+
|
|
84
|
+
### Installation
|
|
85
|
+
|
|
86
|
+
Both versions use the same package:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
npm install @cetusprotocol/aggregator-sdk
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Key Changes
|
|
93
|
+
|
|
94
|
+
1. **Client Initialization**
|
|
95
|
+
|
|
96
|
+
```typescript
|
|
97
|
+
// V2 (Legacy)
|
|
98
|
+
const client = new AggregatorClient({})
|
|
99
|
+
|
|
100
|
+
// V3 (New)
|
|
101
|
+
const client = new AggregatorClient({})
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
2. **Router Finding**
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
// Both versions use the same API
|
|
108
|
+
const routers = await client.findRouters({
|
|
109
|
+
from: "0x2::sui::SUI",
|
|
110
|
+
target:
|
|
111
|
+
"0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS",
|
|
112
|
+
amount: new BN(1000000),
|
|
113
|
+
byAmountIn: true,
|
|
114
|
+
})
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
3. **Transaction Building**
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
// V2 Method
|
|
121
|
+
await client.buildRouterSwap({
|
|
122
|
+
routers,
|
|
123
|
+
txb,
|
|
124
|
+
inputCoin,
|
|
125
|
+
slippage: 0.01,
|
|
126
|
+
})
|
|
127
|
+
|
|
128
|
+
// V3 Method (Recommended)
|
|
129
|
+
await client.fastRouterSwap({
|
|
130
|
+
routers,
|
|
131
|
+
txb,
|
|
132
|
+
slippage: 0.01,
|
|
133
|
+
})
|
|
134
|
+
|
|
135
|
+
// V3 Alternative (For PTB building)
|
|
136
|
+
const targetCoin = await client.routerSwap({
|
|
137
|
+
routers,
|
|
138
|
+
txb,
|
|
139
|
+
inputCoin,
|
|
140
|
+
slippage: 0.01,
|
|
141
|
+
})
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
4. **Benefits of Migration**
|
|
145
|
+
- Reduced gas costs through transaction merging
|
|
146
|
+
- Better transaction traceability
|
|
147
|
+
- Improved error handling and reliability
|
|
148
|
+
- Access to latest DEX integrations
|
|
33
149
|
|
|
34
150
|
## Install
|
|
35
151
|
|
|
@@ -132,18 +248,20 @@ CetusAggregatorV2ExtendV1 = { git = "https://github.com/CetusProtocol/aggregator
|
|
|
132
248
|
CetusAggregatorV2ExtendV2 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2-extend-v2", rev = "mainnet", override = true }
|
|
133
249
|
```
|
|
134
250
|
|
|
135
|
-
# Simple Aggregator Contract Interface
|
|
251
|
+
# Simple Aggregator Contract Interface
|
|
252
|
+
|
|
253
|
+
- include: cetus, flowxv3, turbos, bluefin, haedalhmm, momentum, obric
|
|
136
254
|
|
|
137
255
|
## Tags corresponding to different networks
|
|
138
256
|
|
|
139
257
|
| Contract | Tag of Repo | Latest published at address |
|
|
140
258
|
| --------------------- | ----------- | ------------------------------------------------------------------ |
|
|
141
|
-
| CetusAggregatorSimple | mainnet |
|
|
259
|
+
| CetusAggregatorSimple | mainnet | 0x44ca6438ab034be95cedfca7d4070e6d33fa12e088e9dce13abb1bf055093264 |
|
|
142
260
|
|
|
143
261
|
## Example
|
|
144
262
|
|
|
145
263
|
```
|
|
146
|
-
CetusAggregatorSimple = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2/simple-mainnet", rev = "mainnet-v1.
|
|
264
|
+
CetusAggregatorSimple = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2/simple-mainnet", rev = "mainnet-v1.50.2", override = true }
|
|
147
265
|
```
|
|
148
266
|
|
|
149
267
|
## Usage
|