@rhea-finance/cross-chain-aggregation-dex 1.0.6 → 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.
- package/README.md +277 -270
- package/dist/executors/aptos.d.mts +19 -0
- package/dist/executors/aptos.d.ts +19 -0
- package/dist/executors/aptos.js +140 -0
- package/dist/executors/aptos.js.map +1 -0
- package/dist/executors/aptos.mjs +138 -0
- package/dist/executors/aptos.mjs.map +1 -0
- package/dist/executors/bitcoin.d.mts +22 -0
- package/dist/executors/bitcoin.d.ts +22 -0
- package/dist/executors/bitcoin.js +153 -0
- package/dist/executors/bitcoin.js.map +1 -0
- package/dist/executors/bitcoin.mjs +151 -0
- package/dist/executors/bitcoin.mjs.map +1 -0
- package/dist/executors/evm.d.mts +18 -0
- package/dist/executors/evm.d.ts +18 -0
- package/dist/executors/evm.js +233 -0
- package/dist/executors/evm.js.map +1 -0
- package/dist/executors/evm.mjs +231 -0
- package/dist/executors/evm.mjs.map +1 -0
- package/dist/executors/near.d.mts +18 -0
- package/dist/executors/near.d.ts +18 -0
- package/dist/executors/near.js +162 -0
- package/dist/executors/near.js.map +1 -0
- package/dist/executors/near.mjs +160 -0
- package/dist/executors/near.mjs.map +1 -0
- package/dist/executors/solana.d.mts +20 -0
- package/dist/executors/solana.d.ts +20 -0
- package/dist/executors/solana.js +151 -0
- package/dist/executors/solana.js.map +1 -0
- package/dist/executors/solana.mjs +149 -0
- package/dist/executors/solana.mjs.map +1 -0
- package/dist/executors/sui.d.mts +19 -0
- package/dist/executors/sui.d.ts +19 -0
- package/dist/executors/sui.js +154 -0
- package/dist/executors/sui.js.map +1 -0
- package/dist/executors/sui.mjs +152 -0
- package/dist/executors/sui.mjs.map +1 -0
- package/dist/executors/tron.d.mts +24 -0
- package/dist/executors/tron.d.ts +24 -0
- package/dist/executors/tron.js +161 -0
- package/dist/executors/tron.js.map +1 -0
- package/dist/executors/tron.mjs +159 -0
- package/dist/executors/tron.mjs.map +1 -0
- package/dist/executors/zcash.d.mts +19 -0
- package/dist/executors/zcash.d.ts +19 -0
- package/dist/executors/zcash.js +158 -0
- package/dist/executors/zcash.js.map +1 -0
- package/dist/executors/zcash.mjs +156 -0
- package/dist/executors/zcash.mjs.map +1 -0
- package/dist/index.d.mts +278 -250
- package/dist/index.d.ts +278 -250
- package/dist/index.js +2369 -573
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2340 -560
- package/dist/index.mjs.map +1 -1
- package/dist/registry-DRYUqs7T.d.mts +532 -0
- package/dist/registry-DRYUqs7T.d.ts +532 -0
- package/dist/shared-BdH3hWuP.d.ts +23 -0
- package/dist/shared-BqpFeosz.d.mts +23 -0
- package/package.json +51 -17
package/README.md
CHANGED
|
@@ -1,355 +1,362 @@
|
|
|
1
1
|
# @rhea-finance/cross-chain-aggregation-dex
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
TypeScript SDK for the unified multi-chain Swap API. It provides raw and normalized quote, build, execution, order status, report, and history interfaces without coupling the core package to a wallet or UI framework.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Supported chain families: EVM, Solana, Aptos, NEAR, Tron, Bitcoin, Zcash, and Sui.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- 🌉 **Cross-chain Support**: Integrates with NearIntents for cross-chain swaps
|
|
9
|
-
- 🔀 **Pre-swap Handling**: Automatically handles conversion from non-bluechip tokens to bluechip tokens
|
|
10
|
-
- 📦 **Type Safety**: Complete TypeScript type definitions
|
|
11
|
-
- 🔌 **Adapter Pattern**: Abstracts dependencies through adapter interfaces for easy integration
|
|
12
|
-
|
|
13
|
-
## Installation
|
|
7
|
+
## Install
|
|
14
8
|
|
|
15
9
|
```bash
|
|
16
|
-
npm install @rhea-finance/cross-chain-aggregation-dex
|
|
17
|
-
# or
|
|
18
10
|
pnpm add @rhea-finance/cross-chain-aggregation-dex
|
|
19
|
-
# or
|
|
20
|
-
yarn add @rhea-finance/cross-chain-aggregation-dex
|
|
21
11
|
```
|
|
22
12
|
|
|
23
|
-
## Quick
|
|
13
|
+
## Quick start
|
|
24
14
|
|
|
25
|
-
|
|
15
|
+
All token amounts are base-unit decimal strings. Slippage uses basis points (`50` means 0.5%).
|
|
26
16
|
|
|
27
|
-
|
|
17
|
+
```ts
|
|
18
|
+
import { SwapClient, type QuoteRequest } from "@rhea-finance/cross-chain-aggregation-dex";
|
|
28
19
|
|
|
29
|
-
|
|
30
|
-
import {
|
|
31
|
-
FindPathAdapter,
|
|
32
|
-
IntentsQuotationAdapter,
|
|
33
|
-
NearChainAdapter,
|
|
34
|
-
ConfigAdapter,
|
|
35
|
-
} from "@rhea-finance/cross-chain-aggregation-dex";
|
|
20
|
+
const getAccessToken = async () => sessionStorage.getItem("access-token") ?? "";
|
|
36
21
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
`https://smartrouter.rhea.finance/findPath?${new URLSearchParams({
|
|
42
|
-
amountIn: params.amountIn,
|
|
43
|
-
tokenIn: params.tokenIn,
|
|
44
|
-
tokenOut: params.tokenOut,
|
|
45
|
-
pathDeep: "3",
|
|
46
|
-
slippage: String(params.slippage),
|
|
47
|
-
})}`
|
|
48
|
-
);
|
|
49
|
-
return response.json();
|
|
50
|
-
},
|
|
51
|
-
};
|
|
22
|
+
const client = new SwapClient({
|
|
23
|
+
baseUrl: "https://api.rhea.finance",
|
|
24
|
+
getAccessToken,
|
|
25
|
+
});
|
|
52
26
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
pathDeep: "2",
|
|
63
|
-
chainId: "0",
|
|
64
|
-
routerCount: "1",
|
|
65
|
-
skipUnwrapNativeToken: "false",
|
|
66
|
-
user: params.user,
|
|
67
|
-
receiveUser: params.receiveUser,
|
|
68
|
-
})}`
|
|
69
|
-
);
|
|
70
|
-
return response.json();
|
|
27
|
+
const request: QuoteRequest = {
|
|
28
|
+
fromChain: "btc",
|
|
29
|
+
toChain: "near",
|
|
30
|
+
tokenIn: {
|
|
31
|
+
chain: "btc",
|
|
32
|
+
address: "btc",
|
|
33
|
+
symbol: "BTC",
|
|
34
|
+
decimals: 8,
|
|
35
|
+
isNative: true,
|
|
71
36
|
},
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
// Call your NearIntents API
|
|
78
|
-
const response = await fetch("https://your-api.com/intents/quote", {
|
|
79
|
-
method: "POST",
|
|
80
|
-
body: JSON.stringify(params),
|
|
81
|
-
});
|
|
82
|
-
return response.json();
|
|
37
|
+
tokenOut: {
|
|
38
|
+
chain: "near",
|
|
39
|
+
address: "wrap.near",
|
|
40
|
+
symbol: "wNEAR",
|
|
41
|
+
decimals: 24,
|
|
83
42
|
},
|
|
43
|
+
amountIn: "100000",
|
|
44
|
+
slippageBps: 50,
|
|
45
|
+
sender: "bc1...",
|
|
46
|
+
recipient: "alice.near",
|
|
84
47
|
};
|
|
85
48
|
|
|
86
|
-
|
|
87
|
-
const
|
|
88
|
-
async call({ transactions }) {
|
|
89
|
-
// Use your Near wallet or RPC to call contracts
|
|
90
|
-
// Return { status: "success", txHash: "..." }
|
|
91
|
-
},
|
|
92
|
-
async view({ contractId, methodName, args }) {
|
|
93
|
-
// Use your Near RPC to view contract state
|
|
94
|
-
},
|
|
95
|
-
};
|
|
49
|
+
const quote = await client.quote(request);
|
|
50
|
+
const build = await client.buildSwap({ quote });
|
|
96
51
|
|
|
97
|
-
//
|
|
98
|
-
|
|
99
|
-
getRefExchangeId: () => "v2.ref-finance.near",
|
|
100
|
-
getWrapNearContractId: () => "wrap.near",
|
|
101
|
-
getFindPathUrl: () => "https://smartrouter.ref.finance",
|
|
102
|
-
getTokenStorageDepositRead: () => "1250000000000000000000",
|
|
103
|
-
};
|
|
52
|
+
// build is safe to inspect or send to another process.
|
|
53
|
+
// Register a chain executor before calling executeSwap.
|
|
104
54
|
```
|
|
105
55
|
|
|
106
|
-
|
|
56
|
+
`buildSwap()` never opens a wallet. To execute a build, inject one or more `ChainExecutor` implementations when creating the client:
|
|
107
57
|
|
|
108
|
-
```
|
|
109
|
-
|
|
58
|
+
```ts
|
|
59
|
+
const clientWithExecutor = new SwapClient({
|
|
60
|
+
baseUrl: "https://api.rhea.finance",
|
|
61
|
+
getAccessToken,
|
|
62
|
+
executors: [bitcoinExecutor],
|
|
63
|
+
});
|
|
110
64
|
|
|
111
|
-
const
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
nearChainAdapter,
|
|
115
|
-
configAdapter,
|
|
65
|
+
const result = await clientWithExecutor.executeSwap({
|
|
66
|
+
build,
|
|
67
|
+
waitFor: "submitted",
|
|
116
68
|
});
|
|
117
69
|
```
|
|
118
70
|
|
|
119
|
-
###
|
|
71
|
+
### Executor adapters
|
|
120
72
|
|
|
121
|
-
|
|
122
|
-
import { TokenInfo } from "@rhea-finance/cross-chain-aggregation-dex";
|
|
73
|
+
Each executor is imported from its own subpath and accepts a wallet-neutral adapter. The application decides whether that adapter wraps a browser wallet, server signer, RPC service, or HSM.
|
|
123
74
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
};
|
|
130
|
-
|
|
131
|
-
const
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
75
|
+
```ts
|
|
76
|
+
import { SwapClient } from "@rhea-finance/cross-chain-aggregation-dex";
|
|
77
|
+
import {
|
|
78
|
+
createEvmExecutor,
|
|
79
|
+
type EvmWalletAdapter,
|
|
80
|
+
} from "@rhea-finance/cross-chain-aggregation-dex/executors/evm";
|
|
81
|
+
|
|
82
|
+
const evmWallet: EvmWalletAdapter = {
|
|
83
|
+
getIdentityKey: () => wallet.address,
|
|
84
|
+
signMessage: (message) => wallet.signMessage(message),
|
|
85
|
+
sendTransaction: async (tx) => {
|
|
86
|
+
const response = await wallet.sendTransaction({
|
|
87
|
+
to: tx.to,
|
|
88
|
+
data: tx.data,
|
|
89
|
+
value: tx.value,
|
|
90
|
+
gasLimit: tx.gasLimit,
|
|
91
|
+
});
|
|
92
|
+
return { txHash: response.hash, raw: response };
|
|
93
|
+
},
|
|
94
|
+
signTypedData: async (request) =>
|
|
95
|
+
wallet.signTypedData(
|
|
96
|
+
request.typedData.domain,
|
|
97
|
+
request.typedData.types,
|
|
98
|
+
request.typedData.message
|
|
99
|
+
),
|
|
100
|
+
waitForTransaction: async (txHash) => provider.waitForTransaction(txHash),
|
|
136
101
|
};
|
|
137
102
|
|
|
138
|
-
const
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
slippage: 50, // 0.5% (50 basis points)
|
|
143
|
-
swapType: "EXACT_INPUT",
|
|
103
|
+
const client = new SwapClient({
|
|
104
|
+
baseUrl: "https://api.rhea.finance",
|
|
105
|
+
getAccessToken,
|
|
106
|
+
executors: [createEvmExecutor(evmWallet)],
|
|
144
107
|
});
|
|
108
|
+
```
|
|
145
109
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
}
|
|
151
|
-
|
|
152
|
-
}
|
|
110
|
+
Other executor subpaths follow the same pattern:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
import { createSolanaExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/solana";
|
|
114
|
+
import { createAptosExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/aptos";
|
|
115
|
+
import { createNearExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/near";
|
|
116
|
+
import { createTronExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/tron";
|
|
117
|
+
import { createBitcoinExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/bitcoin";
|
|
118
|
+
import { createZcashExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/zcash";
|
|
119
|
+
import { createSuiExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/sui";
|
|
153
120
|
```
|
|
154
121
|
|
|
155
|
-
|
|
122
|
+
Bitcoin requires `feeRate` in the build or a configured fallback:
|
|
156
123
|
|
|
157
|
-
```
|
|
158
|
-
const
|
|
159
|
-
|
|
160
|
-
recipient: "user.near",
|
|
161
|
-
depositAddress: "deposit.near", // optional
|
|
124
|
+
```ts
|
|
125
|
+
const bitcoinExecutor = createBitcoinExecutor(bitcoinWallet, {
|
|
126
|
+
defaultFeeRate: 4,
|
|
162
127
|
});
|
|
163
|
-
|
|
164
|
-
if (result.success) {
|
|
165
|
-
console.log("Transaction hash:", result.txHash);
|
|
166
|
-
} else {
|
|
167
|
-
console.error("Swap failed:", result.error);
|
|
168
|
-
}
|
|
169
128
|
```
|
|
170
129
|
|
|
171
|
-
|
|
130
|
+
Zcash adapters may return `{ requiresUserAction: true }` for legacy wallets that complete transfer confirmation in an external interface. The SDK returns `requires-user-action` without creating a fake transaction hash.
|
|
131
|
+
|
|
132
|
+
`swap({ quote })` is the convenience form of `buildSwap({ quote })` followed by `executeSwap({ build })`. It does not request another quote.
|
|
133
|
+
|
|
134
|
+
## MCA swaps
|
|
135
|
+
|
|
136
|
+
MCA deposit and withdrawal are execution modes of the unified root API. Use the same `client.quote()`, `client.buildSwap()`, `client.swap()`, `client.report()`, and `client.getHistory()` methods as a regular swap. The SDK does not create MCA accounts or query lending positions.
|
|
172
137
|
|
|
173
|
-
|
|
174
|
-
import { completeQuote } from "@rhea-finance/cross-chain-aggregation-dex";
|
|
138
|
+
HTTP endpoint、请求/响应 JSON 和 curl 示例见 [MCA Swap HTTP API 文档](docs/MCA_SWAP_HTTP_API.md)。SDK 调用方式见 [MCA Swap SDK 文档](docs/MCA_SWAP_API.md)。
|
|
175
139
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
140
|
+
### Deposit into an MCA
|
|
141
|
+
|
|
142
|
+
The destination asset address is the Burrow token id expected by the Swap API. Execution reuses the registered source-chain executor.
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
const quote = await client.quote({
|
|
146
|
+
flow: "deposit",
|
|
147
|
+
mcaAccountId: "account.near",
|
|
148
|
+
fromChain: "1",
|
|
149
|
+
toChain: "near",
|
|
150
|
+
tokenIn: ethereumUsdc,
|
|
151
|
+
tokenOut: mcaUsdc,
|
|
152
|
+
amountIn: "1000000",
|
|
153
|
+
slippageBps: 50,
|
|
154
|
+
sender: "0x...",
|
|
155
|
+
recipient: "account.near",
|
|
156
|
+
signerChain: "evm",
|
|
157
|
+
collateral: {
|
|
158
|
+
useAsCollateral: true,
|
|
182
159
|
},
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
const result = await client.swap({ quote, waitFor: "completed" });
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
The report includes `multi_addr`. Its `tx_type` remains `same-chain` or `cross-chain`, matching the unified Swap API.
|
|
166
|
+
|
|
167
|
+
### Withdraw directly to NEAR
|
|
168
|
+
|
|
169
|
+
Register a NEAR executor and request the NEAR path. The SDK parses `nearMcaWithdrawTx`, builds the MCA `exec` function call, and asks the injected NEAR wallet to send it. This path does not create an additional off-chain MCA message signature.
|
|
170
|
+
|
|
171
|
+
```ts
|
|
172
|
+
const quote = await client.quote({
|
|
173
|
+
flow: "withdraw",
|
|
174
|
+
mcaAccountId: "account.near",
|
|
175
|
+
fromChain: "near",
|
|
176
|
+
toChain: "near",
|
|
177
|
+
tokenIn: mcaUsdc,
|
|
178
|
+
tokenOut: nearUsdc,
|
|
179
|
+
amountIn: "1000000",
|
|
180
|
+
slippageBps: 50,
|
|
181
|
+
sender: "account.near",
|
|
182
|
+
recipient: "alice.near",
|
|
183
|
+
signerChain: "near",
|
|
184
|
+
collateral: {
|
|
185
|
+
needDecrease: false,
|
|
186
|
+
decreaseAmountBurrow: "0",
|
|
188
187
|
},
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
188
|
+
executionPreference: "near",
|
|
189
|
+
boundNearAccountId: "alice.near",
|
|
190
|
+
});
|
|
191
|
+
|
|
192
|
+
await client.swap({ quote, waitFor: "completed" });
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
With `executionPreference: "auto"`, NEAR direct execution is selected only when the destination chain is NEAR and `recipient` exactly matches `boundNearAccountId`.
|
|
196
|
+
|
|
197
|
+
### Withdraw through the multichain relayer
|
|
198
|
+
|
|
199
|
+
For other destination chains, expose `getIdentityKey()` and `signMessage()` on the connected wallet adapter used by its registered executor. The SDK signs the exact `messageToSign` returned by the API, then submits `mcaRelayer` through `POST /api/swap/swap`. No source-chain executor broadcasts a transaction for this path.
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
const quote = await client.quote({
|
|
203
|
+
flow: "withdraw",
|
|
204
|
+
mcaAccountId: "account.near",
|
|
205
|
+
fromChain: "near",
|
|
206
|
+
toChain: "1",
|
|
207
|
+
tokenIn: mcaUsdc,
|
|
208
|
+
tokenOut: ethereumUsdc,
|
|
209
|
+
amountIn: "1000000",
|
|
210
|
+
slippageBps: 50,
|
|
211
|
+
sender: "account.near",
|
|
212
|
+
recipient: wallet.address,
|
|
213
|
+
signerChain: "evm",
|
|
214
|
+
collateral: {
|
|
215
|
+
needDecrease: true,
|
|
216
|
+
decreaseAmountBurrow: "1000000",
|
|
217
|
+
withdrawAll: true,
|
|
194
218
|
},
|
|
195
|
-
|
|
219
|
+
executionPreference: "relayer",
|
|
220
|
+
});
|
|
196
221
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
targetChain: "bsc",
|
|
203
|
-
amountIn: "1000000000000000000",
|
|
204
|
-
slippage: 50,
|
|
205
|
-
recipient: "0x...", // Target chain address
|
|
206
|
-
refundTo: "user.near",
|
|
222
|
+
await client.swap({
|
|
223
|
+
quote,
|
|
224
|
+
waitFor: "completed",
|
|
225
|
+
beforeSign(preview) {
|
|
226
|
+
showMcaSignatureConfirmation(preview);
|
|
207
227
|
},
|
|
208
|
-
|
|
209
|
-
intentsQuotationAdapter,
|
|
210
|
-
dexRouter: router,
|
|
211
|
-
bluechipTokens,
|
|
212
|
-
configAdapter,
|
|
213
|
-
}
|
|
214
|
-
);
|
|
215
|
-
|
|
216
|
-
console.log("Deposit address:", completeQuoteResult.intents.depositAddress);
|
|
217
|
-
console.log("Final amount out:", completeQuoteResult.finalAmountOut);
|
|
218
|
-
|
|
219
|
-
if (completeQuoteResult.preSwap) {
|
|
220
|
-
console.log("Pre-swap required:", completeQuoteResult.preSwap.quote);
|
|
221
|
-
}
|
|
228
|
+
});
|
|
222
229
|
```
|
|
223
230
|
|
|
224
|
-
|
|
231
|
+
Supported MCA signer identity formats are EVM, Solana, Bitcoin, NEAR, Aptos, Sui, Zcash, and Tron. Wallet implementations remain application-owned:
|
|
225
232
|
|
|
226
|
-
|
|
233
|
+
```ts
|
|
234
|
+
import {
|
|
235
|
+
formatMcaWallet,
|
|
236
|
+
selectMcaSigner,
|
|
237
|
+
} from "@rhea-finance/cross-chain-aggregation-dex";
|
|
227
238
|
|
|
228
|
-
|
|
239
|
+
formatMcaWallet("evm", "0xAbC"); // { EVM: "AbC" }
|
|
229
240
|
|
|
230
|
-
|
|
241
|
+
const signer = selectMcaSigner(boundMcaWallets, connectedSignerIdentities);
|
|
242
|
+
```
|
|
231
243
|
|
|
232
|
-
|
|
233
|
-
- `tokenIn`: Input token information
|
|
234
|
-
- `tokenOut`: Output token information
|
|
235
|
-
- `amountIn`: Input amount (string format, considering decimals)
|
|
236
|
-
- `slippage`: Slippage tolerance (prefer bps, 50 = 0.5%). Percent/decimal inputs are also accepted.
|
|
237
|
-
- `swapType`: Swap type ("EXACT_INPUT" | "EXACT_OUTPUT")
|
|
244
|
+
The executor registered for the selected chain must expose `signMessage` when the relayer preview requests a message signature. The SDK never receives a private key or recovery phrase.
|
|
238
245
|
|
|
239
|
-
|
|
240
|
-
- `success`: Whether successful
|
|
241
|
-
- `amountOut`: Output amount
|
|
242
|
-
- `minAmountOut`: Minimum output amount (considering slippage)
|
|
243
|
-
- `routes`: Route information
|
|
244
|
-
- `error`: Error message (if failed)
|
|
246
|
+
### Collateral policy
|
|
245
247
|
|
|
246
|
-
|
|
248
|
+
The SDK does not fetch a lending portfolio. Pass collateral decisions explicitly, or calculate the API fields from data already held by the application:
|
|
247
249
|
|
|
248
|
-
|
|
250
|
+
```ts
|
|
251
|
+
import { resolveMcaWithdrawPolicy } from "@rhea-finance/cross-chain-aggregation-dex";
|
|
249
252
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
253
|
+
const collateral = resolveMcaWithdrawPolicy({
|
|
254
|
+
collateralBalance: "12.5",
|
|
255
|
+
availableBalance: "1000000",
|
|
256
|
+
amountIn: "999999",
|
|
257
|
+
isMax: false,
|
|
258
|
+
});
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
`withdrawAll` becomes true for max selection, exact available balance, or a ratio of at least `0.999999`. The calculation uses decimal strings and `BigInt`, not floating-point arithmetic.
|
|
254
262
|
|
|
255
|
-
|
|
256
|
-
- `success`: Whether successful
|
|
257
|
-
- `txHash`: Transaction hash
|
|
258
|
-
- `txHashArray`: Transaction hash array (if multiple transactions)
|
|
259
|
-
- `error`: Error message (if failed)
|
|
263
|
+
MCA history uses the MCA account id as the server-side history search key. The backend matches this value against `sender`, `recipient`, and `multi_addr`:
|
|
260
264
|
|
|
261
|
-
|
|
265
|
+
```ts
|
|
266
|
+
const history = await client.getHistory({
|
|
267
|
+
sender: "account.near",
|
|
268
|
+
});
|
|
269
|
+
```
|
|
262
270
|
|
|
263
|
-
|
|
271
|
+
The SDK preserves the server page instead of filtering `record.multi_addr` again. Address fields may be presentation-normalized by the API, so callers should not require exact equality with the MCA account id.
|
|
264
272
|
|
|
265
|
-
|
|
266
|
-
- `sourceToken`: Source token
|
|
267
|
-
- `targetToken`: Target token
|
|
268
|
-
- `sourceChain`: Source chain
|
|
269
|
-
- `targetChain`: Target chain
|
|
270
|
-
- `amountIn`: Input amount
|
|
271
|
-
- `slippage`: Slippage tolerance
|
|
272
|
-
- `recipient`: Recipient address
|
|
273
|
-
- `refundTo`: Refund address (optional)
|
|
273
|
+
## API surfaces
|
|
274
274
|
|
|
275
|
-
|
|
276
|
-
- `intentsQuotationAdapter`: NearIntents quotation adapter
|
|
277
|
-
- `dexRouter`: DEX Router instance
|
|
278
|
-
- `bluechipTokens`: Bluechip tokens configuration
|
|
279
|
-
- `configAdapter`: Configuration adapter
|
|
275
|
+
Normalized methods:
|
|
280
276
|
|
|
281
|
-
|
|
277
|
+
- `quote()`
|
|
278
|
+
- `buildSwap()`
|
|
279
|
+
- `executeSwap()` and `swap()`
|
|
280
|
+
- `getOrderStatus()` and `waitForOrder()`
|
|
281
|
+
- `report()` and `retryReport()`
|
|
282
|
+
- `getHistory()`
|
|
282
283
|
|
|
283
|
-
|
|
284
|
+
Raw methods preserve the unified API `data` shape:
|
|
284
285
|
|
|
285
|
-
|
|
286
|
+
- `quoteRaw()`
|
|
287
|
+
- `buildRaw()`
|
|
288
|
+
- `submitOrderRaw()`
|
|
289
|
+
- `getOrderStatusRaw()`
|
|
290
|
+
- `reportRaw()`
|
|
291
|
+
- `getHistoryRaw()`
|
|
286
292
|
|
|
287
|
-
|
|
293
|
+
## Execution kinds
|
|
288
294
|
|
|
289
|
-
|
|
295
|
+
Build responses are validated and represented as a discriminated union:
|
|
290
296
|
|
|
291
|
-
|
|
297
|
+
- `evm-transaction`
|
|
298
|
+
- `evm-signature`
|
|
299
|
+
- `solana-transaction`
|
|
300
|
+
- `aptos-entry-function`
|
|
301
|
+
- `near-transaction-batch`
|
|
302
|
+
- `tron-transfer`
|
|
303
|
+
- `bitcoin-transfer`
|
|
304
|
+
- `zcash-transfer`
|
|
305
|
+
- `sui-transfer`
|
|
292
306
|
|
|
293
|
-
|
|
307
|
+
The SDK core defines the executor contract and registry. Wallet-specific implementations are injected by the application, so importing the package does not access browser wallet globals.
|
|
294
308
|
|
|
295
|
-
|
|
309
|
+
## Runtime and credentials
|
|
296
310
|
|
|
297
|
-
|
|
311
|
+
- Browsers and Node.js 18+ use the global Fetch API.
|
|
312
|
+
- Node.js 16 requires a compatible `fetch` implementation through `new SwapClient({ fetch })`.
|
|
313
|
+
- Supply credentials with `apiKey` or `getAccessToken`; when both are present, `getAccessToken` takes precedence.
|
|
314
|
+
- The package contains no fixed API credential and never manages private keys or wallet recovery phrases.
|
|
315
|
+
- Use `AbortSignal` on network, build, execute, and polling calls when cancellation is required.
|
|
298
316
|
|
|
299
|
-
|
|
300
|
-
- `LOG_LEVEL=info` - Show info, warn, and error logs
|
|
301
|
-
- `LOG_LEVEL=warn` - Show only warnings and errors (default in production)
|
|
302
|
-
- `LOG_LEVEL=error` - Show only errors
|
|
303
|
-
- `LOG_LEVEL=silent` - Disable all logs
|
|
317
|
+
## Retry and logging
|
|
304
318
|
|
|
305
|
-
|
|
306
|
-
import { logger } from "@rhea-finance/cross-chain-aggregation-dex";
|
|
319
|
+
Quote, history, and order-status requests retry network errors, timeouts, HTTP 429, and retryable 5xx responses twice by default. Build, report, order submission, and wallet execution are never retried automatically.
|
|
307
320
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
321
|
+
```ts
|
|
322
|
+
const client = new SwapClient({
|
|
323
|
+
baseUrl: "https://api.rhea.finance",
|
|
324
|
+
retry: {
|
|
325
|
+
maxRetries: 2,
|
|
326
|
+
baseDelayMs: 250,
|
|
327
|
+
maxDelayMs: 2_000,
|
|
328
|
+
jitter: true,
|
|
329
|
+
},
|
|
330
|
+
logger: {
|
|
331
|
+
log(entry) {
|
|
332
|
+
telemetry.emit(entry.event, entry);
|
|
333
|
+
},
|
|
334
|
+
},
|
|
335
|
+
});
|
|
314
336
|
```
|
|
315
337
|
|
|
316
|
-
|
|
338
|
+
Log entries contain only request stage, endpoint path, attempt, response status, timing, and SDK error code. They do not include credentials, query strings, request bodies, signatures, or serialized transactions.
|
|
317
339
|
|
|
318
|
-
|
|
340
|
+
## Amount conversion
|
|
319
341
|
|
|
320
|
-
|
|
321
|
-
import type {
|
|
322
|
-
TokenInfo,
|
|
323
|
-
QuoteParams,
|
|
324
|
-
QuoteResult,
|
|
325
|
-
ExecuteParams,
|
|
326
|
-
ExecuteResult,
|
|
327
|
-
DexRouter,
|
|
328
|
-
BluechipTokensConfig,
|
|
329
|
-
} from "@rhea-finance/cross-chain-aggregation-dex";
|
|
330
|
-
```
|
|
342
|
+
`parseUnits` and `formatUnits` use string arithmetic and never pass token values through floating-point numbers:
|
|
331
343
|
|
|
332
|
-
|
|
344
|
+
```ts
|
|
345
|
+
import {
|
|
346
|
+
formatUnits,
|
|
347
|
+
parseUnits,
|
|
348
|
+
} from "@rhea-finance/cross-chain-aggregation-dex";
|
|
333
349
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
350
|
+
parseUnits("1.25", 6); // "1250000"
|
|
351
|
+
formatUnits("1250000", 6); // "1.25"
|
|
352
|
+
```
|
|
337
353
|
|
|
338
|
-
|
|
339
|
-
pnpm build
|
|
354
|
+
Both functions reject negative values, scientific notation, malformed input, and unsupported precision. Token decimals must be an integer between 0 and 255.
|
|
340
355
|
|
|
341
|
-
|
|
342
|
-
pnpm type-check
|
|
356
|
+
## History filtering
|
|
343
357
|
|
|
344
|
-
|
|
345
|
-
pnpm dev
|
|
346
|
-
```
|
|
358
|
+
The service handles sender and pagination. `getHistory({ status })` filters the current returned page locally and sets `filteredLocally: true`; server totals remain unchanged.
|
|
347
359
|
|
|
348
360
|
## License
|
|
349
361
|
|
|
350
362
|
MIT
|
|
351
|
-
|
|
352
|
-
## Related Links
|
|
353
|
-
|
|
354
|
-
- [GitHub Repository](https://github.com/rhea-finance/crossChain-aggregation-dex)
|
|
355
|
-
- [Rhea Finance](https://rhea.finance)
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { C as ChainRef, q as ChainExecutor } from '../registry-DRYUqs7T.mjs';
|
|
2
|
+
import { E as ExecutorErrorAdapter, T as TransactionSubmission } from '../shared-BqpFeosz.mjs';
|
|
3
|
+
|
|
4
|
+
interface AptosWalletAdapter extends ExecutorErrorAdapter {
|
|
5
|
+
getChain(): ChainRef | Promise<ChainRef>;
|
|
6
|
+
signAndSubmitTransaction(payload: {
|
|
7
|
+
function: string;
|
|
8
|
+
typeArguments: string[];
|
|
9
|
+
functionArguments: unknown[];
|
|
10
|
+
}, options: {
|
|
11
|
+
signal?: AbortSignal;
|
|
12
|
+
}): Promise<TransactionSubmission>;
|
|
13
|
+
waitForTransaction?(txHash: string, options: {
|
|
14
|
+
signal?: AbortSignal;
|
|
15
|
+
}): Promise<unknown>;
|
|
16
|
+
}
|
|
17
|
+
declare function createAptosExecutor(adapter: AptosWalletAdapter): ChainExecutor<"aptos-entry-function">;
|
|
18
|
+
|
|
19
|
+
export { type AptosWalletAdapter, createAptosExecutor };
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { C as ChainRef, q as ChainExecutor } from '../registry-DRYUqs7T.js';
|
|
2
|
+
import { E as ExecutorErrorAdapter, T as TransactionSubmission } from '../shared-BdH3hWuP.js';
|
|
3
|
+
|
|
4
|
+
interface AptosWalletAdapter extends ExecutorErrorAdapter {
|
|
5
|
+
getChain(): ChainRef | Promise<ChainRef>;
|
|
6
|
+
signAndSubmitTransaction(payload: {
|
|
7
|
+
function: string;
|
|
8
|
+
typeArguments: string[];
|
|
9
|
+
functionArguments: unknown[];
|
|
10
|
+
}, options: {
|
|
11
|
+
signal?: AbortSignal;
|
|
12
|
+
}): Promise<TransactionSubmission>;
|
|
13
|
+
waitForTransaction?(txHash: string, options: {
|
|
14
|
+
signal?: AbortSignal;
|
|
15
|
+
}): Promise<unknown>;
|
|
16
|
+
}
|
|
17
|
+
declare function createAptosExecutor(adapter: AptosWalletAdapter): ChainExecutor<"aptos-entry-function">;
|
|
18
|
+
|
|
19
|
+
export { type AptosWalletAdapter, createAptosExecutor };
|