@rozoai/intent-common 0.1.1 → 0.1.2
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 +481 -81
- package/dist/api/payment.d.ts +16 -3
- package/dist/api/payment.js +10 -0
- package/dist/api/payment.js.map +1 -1
- package/package.json +1 -1
- package/src/api/payment.ts +16 -3
package/README.md
CHANGED
|
@@ -1,134 +1,534 @@
|
|
|
1
1
|
# @rozoai/intent-common
|
|
2
2
|
|
|
3
|
-
Shared types and utilities for RozoAI Intent Pay SDK.
|
|
3
|
+
Shared types and utilities for RozoAI Intent Pay SDK - enabling seamless cross-chain crypto payments.
|
|
4
4
|
|
|
5
|
-
## Installation
|
|
5
|
+
## 📦 Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
8
|
npm install @rozoai/intent-common
|
|
9
|
+
# or
|
|
10
|
+
yarn add @rozoai/intent-common
|
|
11
|
+
# or
|
|
12
|
+
pnpm add @rozoai/intent-common
|
|
9
13
|
```
|
|
10
14
|
|
|
11
|
-
## Quick Start
|
|
15
|
+
## 🚀 Quick Start
|
|
12
16
|
|
|
13
|
-
### Payment
|
|
14
|
-
|
|
15
|
-
Use the new payment API for all new integrations:
|
|
17
|
+
### Basic Payment Flow
|
|
16
18
|
|
|
17
19
|
```typescript
|
|
18
|
-
import {
|
|
20
|
+
import {
|
|
21
|
+
createPayment,
|
|
22
|
+
getPayment,
|
|
23
|
+
PaymentStatus,
|
|
24
|
+
} from "@rozoai/intent-common";
|
|
19
25
|
|
|
20
|
-
// Create a payment
|
|
26
|
+
// 1. Create a payment
|
|
21
27
|
const payment = await createPayment({
|
|
22
28
|
appId: "your-app-id",
|
|
23
29
|
toChain: 8453, // Base
|
|
24
30
|
toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
|
|
25
|
-
toAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
|
|
26
|
-
preferredChain:
|
|
27
|
-
preferredTokenAddress: "
|
|
28
|
-
toUnits: "
|
|
29
|
-
title: "
|
|
31
|
+
toAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", // Recipient address
|
|
32
|
+
preferredChain: 137, // Polygon (user pays from)
|
|
33
|
+
preferredTokenAddress: "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359", // Polygon USDC
|
|
34
|
+
toUnits: "10", // 10 USDC
|
|
35
|
+
title: "Product Purchase",
|
|
36
|
+
description: "Payment for Premium Plan",
|
|
30
37
|
});
|
|
31
38
|
|
|
32
|
-
//
|
|
33
|
-
const
|
|
39
|
+
// 2. Extract bridge details
|
|
40
|
+
const bridgeAddress = payment.source.receiverAddress;
|
|
41
|
+
const bridgeMemo = payment.source.receiverMemo; // For Stellar/Solana
|
|
42
|
+
const amountToPay = payment.source.amount;
|
|
43
|
+
|
|
44
|
+
console.log(`Send ${amountToPay} to ${bridgeAddress}`);
|
|
45
|
+
if (bridgeMemo) {
|
|
46
|
+
console.log(`Include memo: ${bridgeMemo}`);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
// 3. User sends funds to bridge address (via wallet)
|
|
50
|
+
// ... your wallet integration code ...
|
|
51
|
+
|
|
52
|
+
// 4. Poll payment status
|
|
53
|
+
const checkStatus = async () => {
|
|
54
|
+
const response = await getPayment(payment.id);
|
|
55
|
+
const paymentData = response.data;
|
|
56
|
+
|
|
57
|
+
switch (paymentData.status) {
|
|
58
|
+
case PaymentStatus.PaymentUnpaid:
|
|
59
|
+
console.log("Waiting for payment...");
|
|
60
|
+
break;
|
|
61
|
+
case PaymentStatus.PaymentStarted:
|
|
62
|
+
console.log("Payment received, processing...");
|
|
63
|
+
break;
|
|
64
|
+
case PaymentStatus.PaymentCompleted:
|
|
65
|
+
console.log("Payment completed!");
|
|
66
|
+
break;
|
|
67
|
+
case PaymentStatus.PaymentBounced:
|
|
68
|
+
console.log("Payment failed:", paymentData.errorCode);
|
|
69
|
+
break;
|
|
70
|
+
}
|
|
71
|
+
};
|
|
34
72
|
```
|
|
35
73
|
|
|
36
|
-
|
|
74
|
+
> **⚠️ Critical:** After creating a payment, funds MUST be sent to `payment.source.receiverAddress`. If `payment.source.receiverMemo` exists (Stellar/Solana), it MUST be included or the payment will fail.
|
|
75
|
+
|
|
76
|
+
---
|
|
37
77
|
|
|
38
|
-
|
|
78
|
+
## 📖 API Reference
|
|
39
79
|
|
|
40
|
-
|
|
80
|
+
### `createPayment(params)`
|
|
41
81
|
|
|
42
|
-
|
|
82
|
+
Creates a new cross-chain payment intent.
|
|
43
83
|
|
|
44
|
-
|
|
84
|
+
#### Parameters
|
|
85
|
+
|
|
86
|
+
| Parameter | Type | Required | Description |
|
|
87
|
+
| ----------------------- | -------- | -------- | ------------------------------------------------------- |
|
|
88
|
+
| `appId` | `string` | ✅ | Your application ID |
|
|
89
|
+
| `toChain` | `number` | ✅ | Destination chain ID (where recipient receives funds) |
|
|
90
|
+
| `toToken` | `string` | ✅ | Destination token address |
|
|
91
|
+
| `toAddress` | `string` | ✅ | Recipient wallet address |
|
|
92
|
+
| `preferredChain` | `number` | ✅ | Source chain ID (where user pays from) |
|
|
93
|
+
| `preferredTokenAddress` | `string` | ✅ | Source token address (what user pays with) |
|
|
94
|
+
| `toUnits` | `string` | ✅ | Amount in human-readable units (e.g., "10" for 10 USDC) |
|
|
95
|
+
| `title` | `string` | ❌ | Payment title for display |
|
|
96
|
+
| `description` | `string` | ❌ | Payment description |
|
|
97
|
+
| `metadata` | `object` | ❌ | Custom metadata (max 4KB recommended) |
|
|
98
|
+
| `orderId` | `string` | ❌ | Your order reference ID (for idempotency) |
|
|
99
|
+
| `feeType` | `enum` | ❌ | `"exactIn"` or `"exactOut"` (default: `"exactIn"`) |
|
|
100
|
+
| `webhookUrl` | `string` | ❌ | URL to receive payment status updates |
|
|
101
|
+
| `webhookSecret` | `string` | ❌ | Secret for HMAC-SHA256 webhook verification |
|
|
102
|
+
| `receiverMemo` | `string` | ❌ | Memo for Stellar/Solana destinations |
|
|
103
|
+
|
|
104
|
+
#### Response: `PaymentResponse`
|
|
45
105
|
|
|
46
106
|
```typescript
|
|
47
|
-
|
|
107
|
+
{
|
|
108
|
+
id: string; // Payment ID
|
|
109
|
+
appId: string; // Your app ID
|
|
110
|
+
status: PaymentStatus; // Current payment status
|
|
111
|
+
type: FeeType; // Fee calculation type
|
|
112
|
+
|
|
113
|
+
source: {
|
|
114
|
+
receiverAddress: string; // ⚠️ BRIDGE ADDRESS - Send funds here
|
|
115
|
+
receiverMemo?: string; // ⚠️ REQUIRED for Stellar/Solana
|
|
116
|
+
amount: string; // Amount user must send
|
|
117
|
+
chainId: number; // Source chain ID
|
|
118
|
+
tokenAddress: string; // Source token address
|
|
119
|
+
tokenSymbol: string; // Token symbol (e.g., "USDC")
|
|
120
|
+
fee?: string; // Fee amount
|
|
121
|
+
amountReceived?: string; // Actual amount received (after deposit)
|
|
122
|
+
senderAddress?: string; // User's wallet address (after deposit)
|
|
123
|
+
txHash?: string; // Deposit transaction hash
|
|
124
|
+
confirmedAt?: Date; // Deposit confirmation time
|
|
125
|
+
};
|
|
126
|
+
|
|
127
|
+
destination: {
|
|
128
|
+
receiverAddress: string; // Final recipient address
|
|
129
|
+
amount: string; // Amount recipient will receive
|
|
130
|
+
chainId: number; // Destination chain ID
|
|
131
|
+
tokenAddress: string; // Destination token address
|
|
132
|
+
tokenSymbol: string; // Token symbol
|
|
133
|
+
txHash?: string; // Payout transaction hash
|
|
134
|
+
confirmedAt?: Date; // Payout confirmation time
|
|
135
|
+
receiverMemo?: string; // Memo for Stellar/Solana
|
|
136
|
+
};
|
|
137
|
+
|
|
138
|
+
display: {
|
|
139
|
+
title: string; // Payment title
|
|
140
|
+
description?: string; // Payment description
|
|
141
|
+
currency: string; // Display currency (e.g., "USD")
|
|
142
|
+
};
|
|
143
|
+
|
|
144
|
+
orderId: string | null; // Your order reference ID
|
|
145
|
+
metadata: object | null; // Custom metadata
|
|
146
|
+
errorCode: string | null; // Error code (if status is payment_bounced)
|
|
147
|
+
webhookSecret: string | null; // Webhook verification secret
|
|
148
|
+
createdAt: Date; // Creation timestamp
|
|
149
|
+
updatedAt: Date; // Last update timestamp
|
|
150
|
+
expiresAt: Date; // Expiration timestamp
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### `getPayment(paymentId)`
|
|
155
|
+
|
|
156
|
+
Retrieves payment details and status.
|
|
157
|
+
|
|
158
|
+
#### Parameters
|
|
159
|
+
|
|
160
|
+
| Parameter | Type | Required | Description |
|
|
161
|
+
| ----------- | -------- | -------- | --------------------------------- |
|
|
162
|
+
| `paymentId` | `string` | ✅ | Payment ID from `createPayment()` |
|
|
163
|
+
|
|
164
|
+
#### Returns
|
|
165
|
+
|
|
166
|
+
Same `PaymentResponse` object as `createPayment()`.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## 🔄 Payment Status Flow
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
PaymentUnpaid → PaymentStarted → PaymentPayinCompleted → PaymentPayoutCompleted → PaymentCompleted
|
|
174
|
+
↓
|
|
175
|
+
PaymentBounced (on error)
|
|
176
|
+
↓
|
|
177
|
+
PaymentRefunded (if applicable)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Status Definitions
|
|
181
|
+
|
|
182
|
+
| Status | Description |
|
|
183
|
+
| -------------------------- | ------------------------------------------------- |
|
|
184
|
+
| `payment_unpaid` | Payment created, waiting for user deposit |
|
|
185
|
+
| `payment_started` | Deposit detected, processing |
|
|
186
|
+
| `payment_payin_completed` | Deposit confirmed, preparing payout |
|
|
187
|
+
| `payment_payout_completed` | Payout sent, waiting for confirmation |
|
|
188
|
+
| `payment_completed` | Payment fully completed |
|
|
189
|
+
| `payment_bounced` | Payment failed (check `errorCode`) |
|
|
190
|
+
| `payment_refunded` | Payment refunded to user |
|
|
191
|
+
| `payment_expired` | Payment expired (not paid within expiration time) |
|
|
192
|
+
|
|
193
|
+
### Error Codes (when status is `payment_bounced`)
|
|
194
|
+
|
|
195
|
+
| Error Code | Description |
|
|
196
|
+
| ----------------------- | --------------------------------- |
|
|
197
|
+
| `amountTooHigh` | Payment amount exceeds maximum |
|
|
198
|
+
| `amountTooLow` | Payment amount below minimum |
|
|
199
|
+
| `chainUnavailable` | Chain temporarily unavailable |
|
|
200
|
+
| `insufficientLiquidity` | Insufficient bridge liquidity |
|
|
201
|
+
| `invalidRecipient` | Invalid recipient address |
|
|
202
|
+
| `missingTrustline` | Stellar trustline not established |
|
|
203
|
+
| `networkError` | Network/RPC error |
|
|
204
|
+
| `providerError` | External provider error |
|
|
205
|
+
| `serviceMaintenance` | Service under maintenance |
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## 💡 Usage Examples
|
|
210
|
+
|
|
211
|
+
### Example 1: Same-Chain Payment (Base → Stellar)
|
|
212
|
+
|
|
213
|
+
```typescript
|
|
214
|
+
const payment = await createPayment({
|
|
215
|
+
appId: "my-app",
|
|
216
|
+
toChain: 1500, // Base
|
|
217
|
+
toToken: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN", // Base USDC
|
|
218
|
+
toAddress: "GDATMUNQEPN4TPETV47LAKGJELK4DUHHDRPMGD3K5LOHUPXX2DI623KY",
|
|
219
|
+
preferredChain: 8453, // User pays from Base
|
|
220
|
+
preferredTokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // Base USDC
|
|
221
|
+
toUnits: "5", // 5 USDC
|
|
222
|
+
title: "Coffee Purchase",
|
|
223
|
+
});
|
|
48
224
|
|
|
49
|
-
|
|
225
|
+
// User sends 5 USDC to payment.source.receiverAddress on Base
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Example 3: Stellar Payment (with Memo)
|
|
229
|
+
|
|
230
|
+
```typescript
|
|
231
|
+
const payment = await createPayment({
|
|
232
|
+
appId: "my-app",
|
|
233
|
+
toChain: 8453, // Base (destination)
|
|
234
|
+
toToken: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // Base USDC
|
|
235
|
+
toAddress: "0xRecipientAddress",
|
|
236
|
+
preferredChain: 1500, // Stellar (source)
|
|
237
|
+
preferredTokenAddress:
|
|
238
|
+
"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
|
|
239
|
+
toUnits: "50", // 50 USDC
|
|
240
|
+
title: "Invoice #12345",
|
|
241
|
+
});
|
|
242
|
+
|
|
243
|
+
// ⚠️ CRITICAL: Must include memo in Stellar transaction
|
|
244
|
+
const stellarMemo = payment.source.receiverMemo; // Required!
|
|
245
|
+
// User sends 50 USDC to payment.source.receiverAddress WITH memo
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
### Example 4: With Webhooks
|
|
249
|
+
|
|
250
|
+
```typescript
|
|
251
|
+
const payment = await createPayment({
|
|
252
|
+
appId: "my-app",
|
|
50
253
|
toChain: 8453,
|
|
51
|
-
toToken: "
|
|
52
|
-
toAddress: "
|
|
53
|
-
toUnits: "1000000",
|
|
254
|
+
toToken: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
|
|
255
|
+
toAddress: "0xRecipientAddress",
|
|
54
256
|
preferredChain: 137,
|
|
55
|
-
preferredTokenAddress: "
|
|
257
|
+
preferredTokenAddress: "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
|
|
258
|
+
toUnits: "25",
|
|
259
|
+
title: "Order #789",
|
|
260
|
+
webhookUrl: "https://yourdomain.com/api/webhooks/payment",
|
|
261
|
+
webhookSecret: "your-secret-key", // Use to verify webhook signatures
|
|
262
|
+
metadata: {
|
|
263
|
+
orderId: "789",
|
|
264
|
+
customerId: "user_123",
|
|
265
|
+
},
|
|
56
266
|
});
|
|
267
|
+
|
|
268
|
+
// Store payment.webhookSecret securely to verify incoming webhooks
|
|
57
269
|
```
|
|
58
270
|
|
|
59
|
-
###
|
|
271
|
+
### Example 5: Using Chain/Token Constants
|
|
60
272
|
|
|
61
273
|
```typescript
|
|
62
274
|
import {
|
|
63
275
|
base,
|
|
64
|
-
|
|
276
|
+
rozoStellar,
|
|
65
277
|
baseUSDC,
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
getKnownToken,
|
|
278
|
+
rozoStellarUSDC,
|
|
279
|
+
createPayment,
|
|
69
280
|
} from "@rozoai/intent-common";
|
|
70
281
|
|
|
71
|
-
|
|
72
|
-
|
|
282
|
+
const payment = await createPayment({
|
|
283
|
+
appId: "my-app",
|
|
284
|
+
toChain: base.chainId, // 8453
|
|
285
|
+
toToken: baseUSDC.token, // Base USDC address
|
|
286
|
+
toAddress: "0xRecipientAddress",
|
|
287
|
+
preferredChain: rozoStellar.chainId, // 137
|
|
288
|
+
preferredTokenAddress: rozoStellarUSDC.token, // Polygon USDC address
|
|
289
|
+
toUnits: "15",
|
|
290
|
+
title: "Payment with Constants",
|
|
291
|
+
});
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
## 🔗 Supported Chains & Tokens
|
|
297
|
+
|
|
298
|
+
Based on [ROZO API Documentation](https://docs.rozo.ai/integration/api-doc/supported-tokens-and-chains).
|
|
299
|
+
|
|
300
|
+
### Pay In Chains (Source - Where Users Can Pay From)
|
|
301
|
+
|
|
302
|
+
| Chain | Chain ID | Constant | Type | USDC Support | USDT Support |
|
|
303
|
+
| ------------ | -------- | ------------- | ------- | ------------ | ------------ |
|
|
304
|
+
| Ethereum | `1` | `ethereum` | EVM | ✅ | ✅ |
|
|
305
|
+
| Arbitrum | `42161` | `arbitrum` | EVM | ✅ | ✅ |
|
|
306
|
+
| Base | `8453` | `base` | EVM | ✅ | ❌ |
|
|
307
|
+
| BSC | `56` | `bsc` | EVM | ✅ (18 dec) | ✅ (18 dec) |
|
|
308
|
+
| Polygon | `137` | `polygon` | EVM | ✅ | ✅ |
|
|
309
|
+
| Rozo Solana | `900` | `rozoSolana` | Solana | ✅ | ✅ |
|
|
310
|
+
| Rozo Stellar | `1500` | `rozoStellar` | Stellar | ✅ (7 dec) | ❌ |
|
|
311
|
+
|
|
312
|
+
### Pay Out Chains (Destination - Where Recipients Can Receive)
|
|
313
|
+
|
|
314
|
+
| Chain | Chain ID | Constant | Type | USDC Support |
|
|
315
|
+
| ------------ | -------- | ------------- | ------- | ------------ |
|
|
316
|
+
| Base | `8453` | `base` | EVM | ✅ |
|
|
317
|
+
| Rozo Stellar | `1500` | `rozoStellar` | Stellar | ✅ (7 dec) |
|
|
318
|
+
|
|
319
|
+
### Token Addresses
|
|
320
|
+
|
|
321
|
+
<details>
|
|
322
|
+
<summary><strong>Ethereum (Chain ID: 1)</strong></summary>
|
|
323
|
+
|
|
324
|
+
| Token | Address | Decimals | Constant |
|
|
325
|
+
| ----- | -------------------------------------------- | -------- | -------------- |
|
|
326
|
+
| USDC | `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` | 6 | `ethereumUSDC` |
|
|
327
|
+
| USDT | `0xdac17f958d2ee523a2206206994597c13d831ec7` | 6 | `ethereumUSDT` |
|
|
328
|
+
|
|
329
|
+
</details>
|
|
330
|
+
|
|
331
|
+
<details>
|
|
332
|
+
<summary><strong>Arbitrum (Chain ID: 42161)</strong></summary>
|
|
333
|
+
|
|
334
|
+
| Token | Address | Decimals | Constant |
|
|
335
|
+
| ----- | -------------------------------------------- | -------- | -------------- |
|
|
336
|
+
| USDC | `0xaf88d065e77c8cc2239327c5edb3a432268e5831` | 6 | `arbitrumUSDC` |
|
|
337
|
+
| USDT | `0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9` | 6 | `arbitrumUSDT` |
|
|
73
338
|
|
|
74
|
-
|
|
75
|
-
|
|
339
|
+
</details>
|
|
340
|
+
|
|
341
|
+
<details>
|
|
342
|
+
<summary><strong>Base (Chain ID: 8453)</strong></summary>
|
|
343
|
+
|
|
344
|
+
| Token | Address | Decimals | Constant |
|
|
345
|
+
| ----- | -------------------------------------------- | -------- | ---------- |
|
|
346
|
+
| USDC | `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913` | 6 | `baseUSDC` |
|
|
347
|
+
|
|
348
|
+
</details>
|
|
349
|
+
|
|
350
|
+
<details>
|
|
351
|
+
<summary><strong>BSC (Chain ID: 56)</strong></summary>
|
|
352
|
+
|
|
353
|
+
| Token | Address | Decimals | Constant |
|
|
354
|
+
| ----- | -------------------------------------------- | -------- | --------- |
|
|
355
|
+
| USDC | `0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d` | 18 | `bscUSDC` |
|
|
356
|
+
| USDT | `0x55d398326f99059ff775485246999027b3197955` | 18 | `bscUSDT` |
|
|
357
|
+
|
|
358
|
+
</details>
|
|
359
|
+
|
|
360
|
+
<details>
|
|
361
|
+
<summary><strong>Polygon (Chain ID: 137)</strong></summary>
|
|
362
|
+
|
|
363
|
+
| Token | Address | Decimals | Constant |
|
|
364
|
+
| ----- | -------------------------------------------- | -------- | ------------- |
|
|
365
|
+
| USDC | `0x3c499c542cef5e3811e1192ce70d8cc03d5c3359` | 6 | `polygonUSDC` |
|
|
366
|
+
| USDT | `0xc2132d05d31c914a87c6611c10748aeb04b58e8f` | 6 | `polygonUSDT` |
|
|
367
|
+
|
|
368
|
+
</details>
|
|
369
|
+
|
|
370
|
+
<details>
|
|
371
|
+
<summary><strong>Rozo Solana (Chain ID: 900)</strong></summary>
|
|
372
|
+
|
|
373
|
+
| Token | Address | Decimals | Constant |
|
|
374
|
+
| ----- | ---------------------------------------------- | -------- | ---------------- |
|
|
375
|
+
| USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | 6 | `rozoSolanaUSDC` |
|
|
376
|
+
| USDT | `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` | 6 | `rozoSolanaUSDT` |
|
|
377
|
+
|
|
378
|
+
</details>
|
|
379
|
+
|
|
380
|
+
<details>
|
|
381
|
+
<summary><strong>Rozo Stellar (Chain ID: 1500)</strong></summary>
|
|
382
|
+
|
|
383
|
+
| Token | Address | Decimals | Constant |
|
|
384
|
+
| ----- | --------------------------------------------------------------- | -------- | ----------------- |
|
|
385
|
+
| USDC | `USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN` | 7 | `rozoStellarUSDC` |
|
|
386
|
+
|
|
387
|
+
</details>
|
|
388
|
+
|
|
389
|
+
---
|
|
390
|
+
|
|
391
|
+
## 🛠️ Utility Functions
|
|
392
|
+
|
|
393
|
+
### Chain Utilities
|
|
394
|
+
|
|
395
|
+
```typescript
|
|
396
|
+
import { getChainById, getChainByName } from "@rozoai/intent-common";
|
|
397
|
+
|
|
398
|
+
// Get chain by ID
|
|
399
|
+
const baseChain = getChainById(8453);
|
|
400
|
+
console.log(baseChain.name); // "Base"
|
|
401
|
+
|
|
402
|
+
// Get chain by name
|
|
403
|
+
const polygonChain = getChainByName("polygon");
|
|
404
|
+
console.log(polygonChain.chainId); // 137
|
|
76
405
|
```
|
|
77
406
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
Based on `supportedTokens` Map in the codebase:
|
|
81
|
-
|
|
82
|
-
| Chain | Chain ID | Constant | Type | Supported Tokens |
|
|
83
|
-
| ------------ | -------- | ------------- | ------- | ---------------- |
|
|
84
|
-
| Arbitrum | 42161 | `arbitrum` | EVM | USDC, USDT |
|
|
85
|
-
| Avalanche | 43114 | `avalanche` | EVM | USDC, USDT |
|
|
86
|
-
| Base | 8453 | `base` | EVM | USDC |
|
|
87
|
-
| Ethereum | 1 | `ethereum` | EVM | USDC, USDT |
|
|
88
|
-
| Gnosis | 100 | `gnosis` | EVM | USDC, USDT |
|
|
89
|
-
| Optimism | 10 | `optimism` | EVM | USDC, USDT |
|
|
90
|
-
| Polygon | 137 | `polygon` | EVM | USDC, USDT |
|
|
91
|
-
| Rozo Solana | 900 | `rozoSolana` | Solana | USDC, USDT |
|
|
92
|
-
| Rozo Stellar | 1500 | `rozoStellar` | Stellar | USDC |
|
|
93
|
-
|
|
94
|
-
### Token Constants
|
|
95
|
-
|
|
96
|
-
| Token | Chain | Constant |
|
|
97
|
-
| ----- | ------------ | ----------------- |
|
|
98
|
-
| USDC | Arbitrum | `arbitrumUSDC` |
|
|
99
|
-
| USDT | Arbitrum | `arbitrumUSDT` |
|
|
100
|
-
| USDC | Avalanche | `avalancheUSDC` |
|
|
101
|
-
| USDT | Avalanche | `avalancheUSDT` |
|
|
102
|
-
| USDC | Base | `baseUSDC` |
|
|
103
|
-
| USDC | Ethereum | `ethereumUSDC` |
|
|
104
|
-
| USDT | Ethereum | `ethereumUSDT` |
|
|
105
|
-
| USDC | Gnosis | `gnosisUSDC` |
|
|
106
|
-
| USDT | Gnosis | `gnosisUSDT` |
|
|
107
|
-
| USDC | Optimism | `optimismUSDC` |
|
|
108
|
-
| USDT | Optimism | `optimismUSDT` |
|
|
109
|
-
| USDC | Polygon | `polygonUSDC` |
|
|
110
|
-
| USDT | Polygon | `polygonUSDT` |
|
|
111
|
-
| USDC | Rozo Solana | `rozoSolanaUSDC` |
|
|
112
|
-
| USDT | Rozo Solana | `rozoSolanaUSDT` |
|
|
113
|
-
| USDC | Rozo Stellar | `rozoStellarUSDC` |
|
|
114
|
-
|
|
115
|
-
**Example:**
|
|
407
|
+
### Token Utilities
|
|
116
408
|
|
|
117
409
|
```typescript
|
|
118
|
-
import {
|
|
410
|
+
import { getKnownToken, getTokensByChain } from "@rozoai/intent-common";
|
|
119
411
|
|
|
120
|
-
//
|
|
121
|
-
const
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
412
|
+
// Get specific token
|
|
413
|
+
const token = getKnownToken(8453, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913");
|
|
414
|
+
console.log(token.symbol); // "USDC"
|
|
415
|
+
console.log(token.decimals); // 6
|
|
416
|
+
|
|
417
|
+
// Get all tokens for a chain
|
|
418
|
+
const baseTokens = getTokensByChain(8453);
|
|
419
|
+
console.log(baseTokens); // Array of token objects
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
### Payment Bridge Configuration
|
|
423
|
+
|
|
424
|
+
```typescript
|
|
425
|
+
import { createPaymentBridgeConfig } from "@rozoai/intent-common";
|
|
426
|
+
|
|
427
|
+
const config = createPaymentBridgeConfig({
|
|
428
|
+
toChain: 8453,
|
|
429
|
+
toToken: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
|
|
430
|
+
toAddress: "0xRecipient",
|
|
431
|
+
toUnits: "100",
|
|
432
|
+
preferredChain: 137,
|
|
433
|
+
preferredTokenAddress: "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
|
|
125
434
|
});
|
|
435
|
+
|
|
436
|
+
console.log(config.preferred); // Source payment details
|
|
437
|
+
console.log(config.destination); // Destination payment details
|
|
126
438
|
```
|
|
127
439
|
|
|
128
|
-
|
|
440
|
+
---
|
|
441
|
+
|
|
442
|
+
## 🔐 Webhook Verification
|
|
443
|
+
|
|
444
|
+
When using webhooks, verify incoming requests using HMAC-SHA256:
|
|
445
|
+
|
|
446
|
+
```typescript
|
|
447
|
+
import crypto from "crypto";
|
|
448
|
+
|
|
449
|
+
function verifyWebhook(
|
|
450
|
+
payload: string,
|
|
451
|
+
signature: string,
|
|
452
|
+
secret: string
|
|
453
|
+
): boolean {
|
|
454
|
+
const hmac = crypto.createHmac("sha256", secret);
|
|
455
|
+
const digest = hmac.update(payload).digest("hex");
|
|
456
|
+
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
// In your webhook handler
|
|
460
|
+
app.post("/api/webhooks/payment", (req, res) => {
|
|
461
|
+
const signature = req.headers["x-rozo-signature"];
|
|
462
|
+
const payload = JSON.stringify(req.body);
|
|
463
|
+
|
|
464
|
+
if (!verifyWebhook(payload, signature, payment.webhookSecret)) {
|
|
465
|
+
return res.status(401).send("Invalid signature");
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
// Process webhook
|
|
469
|
+
const { status, id } = req.body;
|
|
470
|
+
console.log(`Payment ${id} status: ${status}`);
|
|
471
|
+
|
|
472
|
+
res.status(200).send("OK");
|
|
473
|
+
});
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
---
|
|
477
|
+
|
|
478
|
+
## 📚 TypeScript Support
|
|
129
479
|
|
|
130
480
|
Full TypeScript definitions included. All exports are typed.
|
|
131
481
|
|
|
132
|
-
|
|
482
|
+
```typescript
|
|
483
|
+
import type {
|
|
484
|
+
PaymentResponse,
|
|
485
|
+
PaymentStatus,
|
|
486
|
+
FeeType,
|
|
487
|
+
CreatePaymentRequest,
|
|
488
|
+
DestinationRequest,
|
|
489
|
+
SourceRequest,
|
|
490
|
+
PaymentErrorCode,
|
|
491
|
+
} from "@rozoai/intent-common";
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
---
|
|
495
|
+
|
|
496
|
+
## ⚠️ Important Notes
|
|
497
|
+
|
|
498
|
+
### Bridge Address & Memo
|
|
499
|
+
|
|
500
|
+
- **Always** send funds to `payment.source.receiverAddress` after creating a payment
|
|
501
|
+
- **For Stellar (chainId: 1500)**: `payment.source.receiverMemo` is **REQUIRED** - transaction will fail without it
|
|
502
|
+
- **For Solana (chainId: 900)**: Include `payment.source.receiverMemo` if present
|
|
503
|
+
- **For EVM chains**: No memo required
|
|
504
|
+
|
|
505
|
+
### Amount Format
|
|
506
|
+
|
|
507
|
+
- Use human-readable units (e.g., `"10"` for 10 USDC, not `"10000000"`)
|
|
508
|
+
- The SDK handles decimal conversion automatically
|
|
509
|
+
- Example: For 1.5 USDC, use `toUnits: "1.5"`
|
|
510
|
+
|
|
511
|
+
### Fee Types
|
|
512
|
+
|
|
513
|
+
- **`exactIn`** (default): Fee deducted from input. Recipient receives `amount - fee`
|
|
514
|
+
- **`exactOut`**: Fee added to input. Recipient receives exact `amount`, user pays `amount + fee`
|
|
515
|
+
|
|
516
|
+
### Expiration
|
|
517
|
+
|
|
518
|
+
- Payments expire after a set period (check `expiresAt` field)
|
|
519
|
+
- Expired payments cannot be completed
|
|
520
|
+
- Always check payment status before displaying to users
|
|
521
|
+
|
|
522
|
+
---
|
|
523
|
+
|
|
524
|
+
## 🔗 Links
|
|
525
|
+
|
|
526
|
+
- [ROZO Documentation](https://docs.rozo.ai)
|
|
527
|
+
- [Supported Chains & Tokens](https://docs.rozo.ai/integration/api-doc/supported-tokens-and-chains)
|
|
528
|
+
- [API Documentation](https://docs.rozo.ai/integration/api-doc)
|
|
529
|
+
|
|
530
|
+
---
|
|
531
|
+
|
|
532
|
+
## 📄 License
|
|
133
533
|
|
|
134
534
|
BSD-2-Clause
|
package/dist/api/payment.d.ts
CHANGED
|
@@ -183,11 +183,14 @@ export interface SourceResponse {
|
|
|
183
183
|
*/
|
|
184
184
|
fee?: string;
|
|
185
185
|
/**
|
|
186
|
-
*
|
|
186
|
+
* **BRIDGE ADDRESS**: This is where you must send the payment.
|
|
187
|
+
* The deposit address for the cross-chain bridge.
|
|
187
188
|
*/
|
|
188
189
|
receiverAddress?: string;
|
|
189
190
|
/**
|
|
190
|
-
*
|
|
191
|
+
* **REQUIRED MEMO**: Must be included in transaction if present.
|
|
192
|
+
* Required for Stellar (chainId: 1500) and Solana (chainId: 900) deposits.
|
|
193
|
+
* The payment will fail if memo is not included when required.
|
|
191
194
|
*/
|
|
192
195
|
receiverMemo?: string;
|
|
193
196
|
/**
|
|
@@ -284,7 +287,7 @@ export interface CreateNewPaymentParams {
|
|
|
284
287
|
webhookSecret?: string;
|
|
285
288
|
/** Memo for Stellar/Solana destinations */
|
|
286
289
|
receiverMemo?: string;
|
|
287
|
-
/** API version to use (
|
|
290
|
+
/** API version to use (v1 or v2). Defaults to v2 */
|
|
288
291
|
apiVersion?: ApiVersion;
|
|
289
292
|
}
|
|
290
293
|
/**
|
|
@@ -293,6 +296,11 @@ export interface CreateNewPaymentParams {
|
|
|
293
296
|
* This function creates a payment using the new backend API structure with
|
|
294
297
|
* separate source and destination objects, enum-based chain IDs and token symbols.
|
|
295
298
|
*
|
|
299
|
+
* **IMPORTANT: After successfully creating a payment:**
|
|
300
|
+
* - Send funds to the bridge address at `response.source.receiverAddress`
|
|
301
|
+
* - If `response.source.receiverMemo` exists, it MUST be included in the transaction
|
|
302
|
+
* (required for Stellar payments with preferredChain: 1500)
|
|
303
|
+
*
|
|
296
304
|
* @param params - Payment creation parameters
|
|
297
305
|
* @returns Promise resolving to the payment response data
|
|
298
306
|
* @throws Error if payment creation fails or required parameters are missing
|
|
@@ -310,6 +318,11 @@ export interface CreateNewPaymentParams {
|
|
|
310
318
|
* appId: "my-app-id",
|
|
311
319
|
* title: "Payment",
|
|
312
320
|
* });
|
|
321
|
+
*
|
|
322
|
+
* // Send funds to the bridge address
|
|
323
|
+
* const bridgeAddress = payment.source.receiverAddress;
|
|
324
|
+
* const bridgeMemo = payment.source.receiverMemo; // Required for Stellar
|
|
325
|
+
* // ... perform transaction to bridgeAddress with memo (if exists)
|
|
313
326
|
* ```
|
|
314
327
|
*/
|
|
315
328
|
export declare function createPayment(params: CreateNewPaymentParams): Promise<PaymentResponse>;
|
package/dist/api/payment.js
CHANGED
|
@@ -51,6 +51,11 @@ var PaymentErrorCode;
|
|
|
51
51
|
* This function creates a payment using the new backend API structure with
|
|
52
52
|
* separate source and destination objects, enum-based chain IDs and token symbols.
|
|
53
53
|
*
|
|
54
|
+
* **IMPORTANT: After successfully creating a payment:**
|
|
55
|
+
* - Send funds to the bridge address at `response.source.receiverAddress`
|
|
56
|
+
* - If `response.source.receiverMemo` exists, it MUST be included in the transaction
|
|
57
|
+
* (required for Stellar payments with preferredChain: 1500)
|
|
58
|
+
*
|
|
54
59
|
* @param params - Payment creation parameters
|
|
55
60
|
* @returns Promise resolving to the payment response data
|
|
56
61
|
* @throws Error if payment creation fails or required parameters are missing
|
|
@@ -68,6 +73,11 @@ var PaymentErrorCode;
|
|
|
68
73
|
* appId: "my-app-id",
|
|
69
74
|
* title: "Payment",
|
|
70
75
|
* });
|
|
76
|
+
*
|
|
77
|
+
* // Send funds to the bridge address
|
|
78
|
+
* const bridgeAddress = payment.source.receiverAddress;
|
|
79
|
+
* const bridgeMemo = payment.source.receiverMemo; // Required for Stellar
|
|
80
|
+
* // ... perform transaction to bridgeAddress with memo (if exists)
|
|
71
81
|
* ```
|
|
72
82
|
*/
|
|
73
83
|
async function createPayment(params) {
|
package/dist/api/payment.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"payment.js","sourceRoot":"","sources":["../../src/api/payment.ts"],"names":[],"mappings":";;;
|
|
1
|
+
{"version":3,"file":"payment.js","sourceRoot":"","sources":["../../src/api/payment.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
package/src/api/payment.ts
CHANGED
|
@@ -193,11 +193,14 @@ export interface SourceResponse {
|
|
|
193
193
|
*/
|
|
194
194
|
fee?: string;
|
|
195
195
|
/**
|
|
196
|
-
*
|
|
196
|
+
* **BRIDGE ADDRESS**: This is where you must send the payment.
|
|
197
|
+
* The deposit address for the cross-chain bridge.
|
|
197
198
|
*/
|
|
198
199
|
receiverAddress?: string;
|
|
199
200
|
/**
|
|
200
|
-
*
|
|
201
|
+
* **REQUIRED MEMO**: Must be included in transaction if present.
|
|
202
|
+
* Required for Stellar (chainId: 1500) and Solana (chainId: 900) deposits.
|
|
203
|
+
* The payment will fail if memo is not included when required.
|
|
201
204
|
*/
|
|
202
205
|
receiverMemo?: string;
|
|
203
206
|
/**
|
|
@@ -301,7 +304,7 @@ export interface CreateNewPaymentParams {
|
|
|
301
304
|
webhookSecret?: string;
|
|
302
305
|
/** Memo for Stellar/Solana destinations */
|
|
303
306
|
receiverMemo?: string;
|
|
304
|
-
/** API version to use (
|
|
307
|
+
/** API version to use (v1 or v2). Defaults to v2 */
|
|
305
308
|
apiVersion?: ApiVersion;
|
|
306
309
|
}
|
|
307
310
|
|
|
@@ -311,6 +314,11 @@ export interface CreateNewPaymentParams {
|
|
|
311
314
|
* This function creates a payment using the new backend API structure with
|
|
312
315
|
* separate source and destination objects, enum-based chain IDs and token symbols.
|
|
313
316
|
*
|
|
317
|
+
* **IMPORTANT: After successfully creating a payment:**
|
|
318
|
+
* - Send funds to the bridge address at `response.source.receiverAddress`
|
|
319
|
+
* - If `response.source.receiverMemo` exists, it MUST be included in the transaction
|
|
320
|
+
* (required for Stellar payments with preferredChain: 1500)
|
|
321
|
+
*
|
|
314
322
|
* @param params - Payment creation parameters
|
|
315
323
|
* @returns Promise resolving to the payment response data
|
|
316
324
|
* @throws Error if payment creation fails or required parameters are missing
|
|
@@ -328,6 +336,11 @@ export interface CreateNewPaymentParams {
|
|
|
328
336
|
* appId: "my-app-id",
|
|
329
337
|
* title: "Payment",
|
|
330
338
|
* });
|
|
339
|
+
*
|
|
340
|
+
* // Send funds to the bridge address
|
|
341
|
+
* const bridgeAddress = payment.source.receiverAddress;
|
|
342
|
+
* const bridgeMemo = payment.source.receiverMemo; // Required for Stellar
|
|
343
|
+
* // ... perform transaction to bridgeAddress with memo (if exists)
|
|
331
344
|
* ```
|
|
332
345
|
*/
|
|
333
346
|
export async function createPayment(
|