@zebec-network/exchange-card-sdk 1.11.3 → 1.11.5
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
CHANGED
|
@@ -1,56 +1,299 @@
|
|
|
1
|
-
# Zebec Card SDK
|
|
1
|
+
# Zebec Exchange Card SDK
|
|
2
2
|
|
|
3
|
-
The Zebec Card SDK
|
|
3
|
+
The Zebec Exchange Card SDK lets developers fund Zebec virtual cards from a variety of non-EVM and alt‑EVM chains by transferring native assets or supported tokens to a Zebec-managed deposit vault. Each chain is exposed through a dedicated service that wraps vault discovery, balance checks, and transaction submission.
|
|
4
|
+
|
|
5
|
+
Supported networks:
|
|
6
|
+
|
|
7
|
+
- Aleo (native credits, USAD/USDCX stablecoins, public & private transfers)
|
|
8
|
+
- Algorand (ALGO and ASA tokens, e.g. USDC)
|
|
9
|
+
- Boba Network (Mainnet / Sepolia testnet — ETH and ERC‑20)
|
|
10
|
+
- NEAR (NEAR and NEP‑141 fungible tokens)
|
|
11
|
+
- Octa Space (OCTA native transfers)
|
|
12
|
+
- Quai Network (QUAI native transfers)
|
|
13
|
+
- Stellar (XLM and USDC)
|
|
14
|
+
- XDB Chain (XDB native transfers)
|
|
15
|
+
- XRPL / Ripple (XRP and issued tokens, with trust line setup)
|
|
16
|
+
|
|
17
|
+
Every service can be toggled between mainnet (production) and testnet via the `sandbox` flag.
|
|
4
18
|
|
|
5
19
|
---
|
|
6
20
|
|
|
7
21
|
## Installation
|
|
8
22
|
|
|
9
|
-
Install the Zebec Card SDK via npm:
|
|
10
|
-
|
|
11
23
|
```bash
|
|
12
|
-
npm i @zebec-
|
|
24
|
+
npm i @zebec-network/exchange-card-sdk
|
|
13
25
|
```
|
|
14
26
|
|
|
27
|
+
Peer/runtime dependencies you may need depending on which service you use: `ethers`, `algosdk`, `xrpl`, `quais`, `@near-js/*`, `@provablehq/sdk`, `@zebec-fintech/stellar-sdk`.
|
|
28
|
+
|
|
29
|
+
## Common Concepts
|
|
30
|
+
|
|
31
|
+
### Sandbox mode
|
|
32
|
+
|
|
33
|
+
Every service constructor accepts an options bag with a `sandbox` boolean. When `sandbox: true`, the service:
|
|
34
|
+
|
|
35
|
+
- Talks to the Zebec sandbox API at `https://dev-super.api.zebec.io`.
|
|
36
|
+
- Uses the testnet RPC for its chain (e.g. Sepolia for Boba, Testnet for Algorand/Stellar/XRPL, Futurenet for XDB, etc.).
|
|
37
|
+
|
|
38
|
+
Defaults to `false` (production) when omitted.
|
|
39
|
+
|
|
40
|
+
### Vault address
|
|
41
|
+
|
|
42
|
+
Each service exposes `fetchVault(symbol?)` which calls Zebec's API to retrieve the destination deposit address (and optional memo `tag`) for a given asset symbol. All `transfer*` methods call `fetchVault` internally with the appropriate symbol — you generally do not need to call it yourself.
|
|
43
|
+
|
|
44
|
+
### API health check
|
|
45
|
+
|
|
46
|
+
The underlying `ZebecCardAPIService` exposes `ping()` which calls `/health` on the card API and returns `true` if reachable, otherwise throws.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
15
50
|
## Quick Start
|
|
16
51
|
|
|
17
|
-
|
|
52
|
+
Pick the service that matches your source chain. Each service takes a wallet/signer and an optional `{ sandbox }` config.
|
|
53
|
+
|
|
54
|
+
### Boba Network (EVM)
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
import { ethers } from "ethers";
|
|
58
|
+
import { BobaService } from "@zebec-network/exchange-card-sdk";
|
|
59
|
+
|
|
60
|
+
const provider = new ethers.JsonRpcProvider("https://sepolia.boba.network");
|
|
61
|
+
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
|
|
62
|
+
|
|
63
|
+
const boba = new BobaService(signer, { sandbox: true });
|
|
64
|
+
|
|
65
|
+
// Native ETH on Boba
|
|
66
|
+
await boba.transferBobaEth({ amount: "0.01" });
|
|
67
|
+
|
|
68
|
+
// ERC‑20 token on Boba
|
|
69
|
+
await boba.transferToken({
|
|
70
|
+
amount: "10",
|
|
71
|
+
symbol: "BOBA-USDC",
|
|
72
|
+
tokenAddress: "0x...",
|
|
73
|
+
});
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Octa Space (EVM)
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
import { ethers } from "ethers";
|
|
80
|
+
import { OctaService } from "@zebec-network/exchange-card-sdk";
|
|
81
|
+
|
|
82
|
+
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
|
|
83
|
+
const octa = new OctaService(signer, { sandbox: false });
|
|
84
|
+
|
|
85
|
+
await octa.transferOcta({ amount: "1.5" });
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Quai Network
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
import { QuaiService, QuaiWallet } from "@zebec-network/exchange-card-sdk";
|
|
92
|
+
|
|
93
|
+
const wallet: QuaiWallet = {
|
|
94
|
+
address: "0x...",
|
|
95
|
+
signAndSendTransaction: async (tx) => {
|
|
96
|
+
/* sign & submit */
|
|
97
|
+
return "0xhash";
|
|
98
|
+
},
|
|
99
|
+
};
|
|
100
|
+
|
|
101
|
+
const quai = new QuaiService(wallet, { sandbox: false });
|
|
102
|
+
const txHash = await quai.transferQuai({ amount: "2.0" });
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### NEAR
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
import { NearService, NearWallet } from "@zebec-network/exchange-card-sdk";
|
|
109
|
+
|
|
110
|
+
const wallet: NearWallet = {
|
|
111
|
+
signerId: "alice.near",
|
|
112
|
+
signAndSendTransaction: async (transaction) => {
|
|
113
|
+
/* submit via near-api-js or wallet selector */
|
|
114
|
+
},
|
|
115
|
+
};
|
|
116
|
+
|
|
117
|
+
const near = new NearService(wallet, { sandbox: false });
|
|
118
|
+
|
|
119
|
+
// Native NEAR
|
|
120
|
+
await near.transferNear({ amount: "1.25" });
|
|
121
|
+
|
|
122
|
+
// NEP‑141 token (e.g. USDC)
|
|
123
|
+
await near.transferTokens({
|
|
124
|
+
amount: "10",
|
|
125
|
+
tokenContractId: "usdc.fakes.testnet",
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`registerAccountInTokenContract({ tokenContractId })` is also available; `transferTokens` already invokes the same `storage_deposit` flow internally when the destination is not yet registered.
|
|
130
|
+
|
|
131
|
+
### XRPL (Ripple)
|
|
132
|
+
|
|
133
|
+
```typescript
|
|
134
|
+
import { XRPLService, XRPLWallet } from "@zebec-network/exchange-card-sdk";
|
|
135
|
+
|
|
136
|
+
const wallet: XRPLWallet = {
|
|
137
|
+
address: "r...",
|
|
138
|
+
signTransaction: async (tx) => {
|
|
139
|
+
/* sign with xrpl.js Wallet or a wallet extension */
|
|
140
|
+
},
|
|
141
|
+
};
|
|
142
|
+
|
|
143
|
+
const xrpl = new XRPLService(wallet, { sandbox: true });
|
|
144
|
+
|
|
145
|
+
// Native XRP
|
|
146
|
+
await xrpl.transferXRP({ amount: "5" });
|
|
147
|
+
|
|
148
|
+
// Issued token (requires a trust line)
|
|
149
|
+
await xrpl.createTrustLine({
|
|
150
|
+
amount: "1000000",
|
|
151
|
+
token: { currency: "USD", issuer: "rIssuer..." },
|
|
152
|
+
});
|
|
153
|
+
await xrpl.transferTokens({
|
|
154
|
+
amount: "10",
|
|
155
|
+
token: { currency: "USD", issuer: "rIssuer..." },
|
|
156
|
+
});
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### Algorand
|
|
18
160
|
|
|
19
|
-
|
|
161
|
+
```typescript
|
|
162
|
+
import algosdk from "algosdk";
|
|
163
|
+
import { AlgorandService, AlgorandWallet } from "@zebec-network/exchange-card-sdk";
|
|
164
|
+
|
|
165
|
+
const wallet: AlgorandWallet = {
|
|
166
|
+
address: "ALGO_ADDRESS",
|
|
167
|
+
signAndSendTransaction: async (txn) => {
|
|
168
|
+
/* sign and submit, return tx id */
|
|
169
|
+
},
|
|
170
|
+
};
|
|
171
|
+
|
|
172
|
+
const algo = new AlgorandService(wallet, { sandbox: true });
|
|
20
173
|
|
|
21
|
-
|
|
174
|
+
// Native ALGO
|
|
175
|
+
await algo.transferAlgo({ amount: "1.0", note: "card top-up" });
|
|
22
176
|
|
|
23
|
-
|
|
177
|
+
// ASA (e.g. USDC asset id 31566704 on mainnet, 10458941 on testnet)
|
|
178
|
+
await algo.transferAsset({ assetId: 10458941, amount: "10" });
|
|
179
|
+
```
|
|
24
180
|
|
|
25
|
-
|
|
26
|
-
For Bittensor Network:
|
|
181
|
+
### Stellar
|
|
27
182
|
|
|
28
183
|
```typescript
|
|
29
|
-
import {
|
|
184
|
+
import { StellarService, StellarWallet } from "@zebec-network/exchange-card-sdk";
|
|
30
185
|
|
|
31
|
-
const
|
|
186
|
+
const wallet: StellarWallet = {
|
|
187
|
+
address: "G...",
|
|
188
|
+
signTransaction: async (xdr) => {
|
|
189
|
+
/* sign and return signed xdr */
|
|
190
|
+
},
|
|
191
|
+
};
|
|
32
192
|
|
|
33
|
-
const
|
|
34
|
-
signer,
|
|
35
|
-
{
|
|
36
|
-
apiKey,
|
|
37
|
-
encryptionKey,
|
|
38
|
-
},
|
|
39
|
-
{
|
|
40
|
-
sandbox: true, // Set to true for development or testing
|
|
41
|
-
},
|
|
42
|
-
);
|
|
43
|
-
````
|
|
193
|
+
const stellar = new StellarService(wallet, { sandbox: true });
|
|
44
194
|
|
|
45
|
-
|
|
195
|
+
await stellar.transferXLM("5");
|
|
196
|
+
await stellar.transferUSDC("10");
|
|
197
|
+
```
|
|
46
198
|
|
|
47
|
-
|
|
199
|
+
`transferXLM` attaches the vault's `tag` as a `Memo.id` automatically. The USDC issuer is preconfigured for both mainnet and testnet (see `STELLAR_USDC_ISSUER`).
|
|
48
200
|
|
|
49
|
-
|
|
201
|
+
### XDB Chain
|
|
50
202
|
|
|
51
|
-
|
|
203
|
+
```typescript
|
|
204
|
+
import { XDBService, XDBWalletInterface } from "@zebec-network/exchange-card-sdk";
|
|
205
|
+
|
|
206
|
+
const wallet: XDBWalletInterface = {
|
|
207
|
+
address: "G...",
|
|
208
|
+
signTransaction: async (xdr) => {
|
|
209
|
+
/* sign and return signed xdr */
|
|
210
|
+
},
|
|
211
|
+
};
|
|
212
|
+
|
|
213
|
+
const xdb = new XDBService(wallet, { sandbox: false });
|
|
214
|
+
await xdb.transferXDB("100");
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Aleo
|
|
52
218
|
|
|
53
219
|
```typescript
|
|
54
|
-
|
|
55
|
-
|
|
220
|
+
import { AleoService, AleoWallet } from "@zebec-network/exchange-card-sdk";
|
|
221
|
+
|
|
222
|
+
const wallet: AleoWallet = {
|
|
223
|
+
address: "aleo1...",
|
|
224
|
+
decrypt: async (ciphertext) => {
|
|
225
|
+
/* decrypt record ciphertext */
|
|
226
|
+
},
|
|
227
|
+
requestRecords: async (program, includePlaintext) => {
|
|
228
|
+
/* fetch records from wallet */
|
|
229
|
+
},
|
|
230
|
+
executeTransaction: async (opts) => {
|
|
231
|
+
/* execute program tx */
|
|
232
|
+
},
|
|
233
|
+
};
|
|
234
|
+
|
|
235
|
+
const aleo = new AleoService(wallet, undefined, { sandbox: false });
|
|
236
|
+
|
|
237
|
+
// Native credits — public or private
|
|
238
|
+
await aleo.transferCredit({ amount: "1.5", transferType: "public" });
|
|
239
|
+
|
|
240
|
+
// Stablecoin (USAD / USDCX) — supports public and compliant private transfers
|
|
241
|
+
await aleo.transferStableCoin({
|
|
242
|
+
programId: "usad_stablecoin.aleo",
|
|
243
|
+
amount: "10",
|
|
244
|
+
transferType: "private",
|
|
245
|
+
});
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
For private stablecoin transfers, `AleoService` automatically:
|
|
249
|
+
|
|
250
|
+
1. Fetches an unspent record with sufficient balance for the program.
|
|
251
|
+
2. Builds a Sealance Merkle exclusion proof against the program's freeze list (`NETWORK_CONFIG[network].freezeListApi`) to prove the sender is not blocklisted.
|
|
252
|
+
|
|
253
|
+
Balance helpers: `getPublicBalance()`, `getPrivateBalance()`, `getPublicTokenBalance(programId, symbol)`, `getPrivateTokenBalance(programId, symbol)`.
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Service Reference
|
|
258
|
+
|
|
259
|
+
| Service | Native transfer | Token transfer | Notes |
|
|
260
|
+
| ----------------- | ----------------- | ------------------------------------ | -------------------------------------------- |
|
|
261
|
+
| `BobaService` | `transferBobaEth` | `transferToken` | Boba Mainnet (288) / Sepolia testnet (28882) |
|
|
262
|
+
| `OctaService` | `transferOcta` | — | Hard-coded chainId `800001` |
|
|
263
|
+
| `QuaiService` | `transferQuai` | — | Mainnet (9) / Testnet (15000) |
|
|
264
|
+
| `NearService` | `transferNear` | `transferTokens` | Auto `storage_deposit` for NEP‑141 |
|
|
265
|
+
| `XRPLService` | `transferXRP` | `transferTokens` + `createTrustLine` | Memo / destination tag handled automatically |
|
|
266
|
+
| `AlgorandService` | `transferAlgo` | `transferAsset` | Validates ASA opt-in on recipient |
|
|
267
|
+
| `StellarService` | `transferXLM` | `transferUSDC` | Submission retries with exponential backoff |
|
|
268
|
+
| `XDBService` | `transferXDB` | — | LiveNet / Futurenet network passphrases |
|
|
269
|
+
| `AleoService` | `transferCredit` | `transferStableCoin` | Public + private with compliance proof |
|
|
270
|
+
|
|
271
|
+
### Utilities
|
|
272
|
+
|
|
273
|
+
The SDK re-exports helpers from `utils`:
|
|
274
|
+
|
|
275
|
+
- `parseAlgo` / `formatAlgo` — ALGO ↔ microAlgo conversion
|
|
276
|
+
- `parseAlgorandAsset` / `formatAlgorandAsset` — ASA base-unit conversion
|
|
277
|
+
- `getAssetDecimals(client, assetId)` — cached ASA decimals lookup
|
|
278
|
+
- `toMicroUnits` / `fromMicroUnits` — generic decimal conversion (used by Aleo)
|
|
279
|
+
- `getTokenBySymbol(symbol, network)` — fetch Aleo token metadata from `api.provable.com`
|
|
280
|
+
|
|
281
|
+
And from `constants`:
|
|
282
|
+
|
|
283
|
+
- `CARD_API_URL` — Production / Sandbox base URLs
|
|
284
|
+
- `NEAR_RPC_URL`, `XRPL_RPC_URL`, `STELLAR_RPC_URL`, `XDB_RPC_URL`, `ALGORAND_RPC_URL`
|
|
285
|
+
- `STELLAR_USDC_ISSUER`, `BITCOIN_ENDPOINTS`, `ALEO_NETWORK_CLIENT_URL`
|
|
286
|
+
- `BOBA_CHAIN_ID`, `QUAI_CHAIN_ID`, `XDB_NETWORK`
|
|
287
|
+
- Default EVM/Quai gas constants, `PLATFORM_FEE`
|
|
288
|
+
|
|
289
|
+
### Raw API client
|
|
290
|
+
|
|
291
|
+
If you need direct access to the Zebec card API:
|
|
292
|
+
|
|
293
|
+
```typescript
|
|
294
|
+
import { ZebecCardAPIService } from "@zebec-network/exchange-card-sdk";
|
|
295
|
+
|
|
296
|
+
const api = new ZebecCardAPIService(true); // sandbox
|
|
297
|
+
await api.ping();
|
|
298
|
+
const vault = await api.fetchVault("XRP");
|
|
56
299
|
```
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Asset, Horizon, Memo, Networks, Operation, TimeoutInfinite, TransactionBuilder, } from "@
|
|
1
|
+
import { Asset, Horizon, Memo, Networks, Operation, TimeoutInfinite, TransactionBuilder, } from "@zebec-fintech/stellar-sdk";
|
|
2
2
|
import { STELLAR_RPC_URL, STELLAR_USDC_ISSUER } from "../constants";
|
|
3
3
|
import { ZebecCardAPIService } from "../helpers/apiHelpers";
|
|
4
4
|
export class StellarService {
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Asset, Horizon, Memo, Operation, TimeoutInfinite, TransactionBuilder, } from "@
|
|
1
|
+
import { Asset, Horizon, Memo, Operation, TimeoutInfinite, TransactionBuilder, } from "@zebec-fintech/stellar-sdk";
|
|
2
2
|
import { XDB_NETWORK, XDB_RPC_URL } from "../constants";
|
|
3
3
|
import { ZebecCardAPIService } from "../helpers/apiHelpers";
|
|
4
4
|
export class XDBService {
|
package/package.json
CHANGED
|
@@ -6,27 +6,27 @@
|
|
|
6
6
|
"@near-js/transactions": "^2.5.1",
|
|
7
7
|
"@near-js/types": "^2.5.1",
|
|
8
8
|
"@near-js/utils": "^2.5.1",
|
|
9
|
-
"@provablehq/sdk": "^0.10.
|
|
10
|
-
"@
|
|
11
|
-
"algosdk": "^3.
|
|
12
|
-
"axios": "^1.
|
|
13
|
-
"bignumber.js": "^
|
|
14
|
-
"ethers": "^6.
|
|
15
|
-
"quais": "^1.0.0-alpha.
|
|
16
|
-
"xrpl": "^4.
|
|
9
|
+
"@provablehq/sdk": "^0.10.5",
|
|
10
|
+
"@zebec-fintech/stellar-sdk": "^15.0.2",
|
|
11
|
+
"algosdk": "^3.5.2",
|
|
12
|
+
"axios": "^1.16.0",
|
|
13
|
+
"bignumber.js": "^11.1.1",
|
|
14
|
+
"ethers": "^6.16.0",
|
|
15
|
+
"quais": "^1.0.0-alpha.54",
|
|
16
|
+
"xrpl": "^4.6.0"
|
|
17
17
|
},
|
|
18
18
|
"description": "An sdk for purchasing silver card in zebec",
|
|
19
19
|
"devDependencies": {
|
|
20
|
-
"@algorandfoundation/algokit-utils": "^9.
|
|
20
|
+
"@algorandfoundation/algokit-utils": "^9.2.0",
|
|
21
21
|
"@near-js/accounts": "^2.5.1",
|
|
22
22
|
"@near-js/keystores": "^2.5.1",
|
|
23
23
|
"@near-js/signers": "^2.5.1",
|
|
24
24
|
"@near-js/tokens": "^2.5.1",
|
|
25
25
|
"@typechain/ethers-v6": "^0.5.1",
|
|
26
26
|
"@types/mocha": "^10.0.10",
|
|
27
|
-
"@types/node": "^25.
|
|
28
|
-
"dotenv": "^17.
|
|
29
|
-
"mocha": "^11.7.
|
|
27
|
+
"@types/node": "^25.7.0",
|
|
28
|
+
"dotenv": "^17.4.2",
|
|
29
|
+
"mocha": "^11.7.5",
|
|
30
30
|
"prettier": "^3.6.2",
|
|
31
31
|
"rimraf": "^6.0.1",
|
|
32
32
|
"ts-mocha": "^11.1.0",
|
|
@@ -46,11 +46,6 @@
|
|
|
46
46
|
"license": "MIT",
|
|
47
47
|
"main": "dist/index.js",
|
|
48
48
|
"name": "@zebec-network/exchange-card-sdk",
|
|
49
|
-
"overrides": {
|
|
50
|
-
"@stellar/stellar-sdk": {
|
|
51
|
-
"axios": "^1.15.0"
|
|
52
|
-
}
|
|
53
|
-
},
|
|
54
49
|
"publishConfig": {
|
|
55
50
|
"access": "public"
|
|
56
51
|
},
|
|
@@ -63,9 +58,10 @@
|
|
|
63
58
|
"clean": "rimraf dist",
|
|
64
59
|
"format": "prettier --write .",
|
|
65
60
|
"gen:typechain": "typechain --target ethers-v6 --out-dir \"src/artifacts/typechain-types\" \"src/artifacts/abi/*.json\"",
|
|
61
|
+
"prepare": "npm run build",
|
|
66
62
|
"test": "ts-mocha -p ./tsconfig.test.json -t 1000000"
|
|
67
63
|
},
|
|
68
64
|
"type": "module",
|
|
69
65
|
"types": "dist/index.d.ts",
|
|
70
|
-
"version": "1.11.
|
|
66
|
+
"version": "1.11.5"
|
|
71
67
|
}
|