@silentswap/sdk 0.0.76 → 0.0.78

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export * from './rpc.js';
 export * from './assets.js';
 export * from './encoding.js';
 export * from './refund.js';
+export { trackOrderViaWebSocket, getOrderTrackingWebSocketUrl, type TrackOrderOptions, type OrderStatusUpdate, } from './order-tracking.js';
 export type { NaiveBase58, NaiveBase93, NaiveHexLower, NaiveHexUpper } from './belt-utils.js';
 export { bytes_to_base58, base58_to_bytes, bytes_to_base93, base93_to_bytes, bytes_to_hex, hex_to_bytes } from './belt-utils.js';
 export * from './address.js';

package/dist/index.js

@@ -17,6 +17,7 @@ export * from './rpc.js';
 export * from './assets.js';
 export * from './encoding.js';
 export * from './refund.js';
+export { trackOrderViaWebSocket, getOrderTrackingWebSocketUrl, } from './order-tracking.js';
 export { bytes_to_base58, base58_to_bytes, bytes_to_base93, base93_to_bytes, bytes_to_hex, hex_to_bytes } from './belt-utils.js';
 export * from './address.js';
 // Export asset-utils functions (AssetInfo-based wrappers)

package/dist/order-tracking.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Order tracking via WebSocket
+ *
+ * Subscribe to order status updates from the SilentSwap API until the order
+ * is fully finalized or the connection times out.
+ */
+import type { OrderStatus, OutputStage } from './swap-executor.js';
+/**
+ * Incremental status update from the WebSocket stream
+ */
+export interface OrderStatusUpdate {
+    type: 'deposit' | 'stage' | 'transaction' | 'error';
+    data: {
+        stage?: OutputStage;
+        index?: number;
+        kind?: string;
+        chain?: string;
+        txId?: string;
+        message?: string;
+        amount?: string;
+        orderId?: string;
+    };
+}
+/**
+ * Options for trackOrderViaWebSocket
+ */
+export interface TrackOrderOptions {
+    /** WebSocket URL (default: derived from mainnet API) */
+    wsUrl?: string;
+    /** Timeout in milliseconds (default: 10 * 60 * 1000 = 10 minutes) */
+    timeoutMs?: number;
+    /** Callback for each status update */
+    onStatus?: (update: OrderStatusUpdate) => void;
+}
+/**
+ * Derive WebSocket URL from REST API base URL
+ * e.g. https://api.silentswap.com -> wss://api.silentswap.com/websocket
+ */
+export declare function getOrderTrackingWebSocketUrl(baseUrl: string): string;
+/**
+ * Track an order until all outputs are finalized via the SilentSwap WebSocket API.
+ * Uses the global WebSocket (available in Node 18+ and browsers).
+ *
+ * @param orderId - Base58 order ID returned when placing the order
+ * @param viewingAuth - Viewing authorization (Base58) from the facilitator group
+ * @param options - Optional wsUrl, timeoutMs, and onStatus callback
+ * @returns Final order status when all outputs are FINALIZED
+ * @throws Error on WebSocket error, invalid response, or timeout
+ */
+export declare function trackOrderViaWebSocket(orderId: string, viewingAuth: string, options?: TrackOrderOptions): Promise<OrderStatus>;

package/dist/order-tracking.js

@@ -0,0 +1,131 @@
+/**
+ * Order tracking via WebSocket
+ *
+ * Subscribe to order status updates from the SilentSwap API until the order
+ * is fully finalized or the connection times out.
+ */
+/** Stage name used to detect completion */
+const STAGE_FINALIZED = 'FINALIZED';
+const DEFAULT_WS_URL = 'wss://api.silentswap.com/websocket';
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * Derive WebSocket URL from REST API base URL
+ * e.g. https://api.silentswap.com -> wss://api.silentswap.com/websocket
+ */
+export function getOrderTrackingWebSocketUrl(baseUrl) {
+    const url = baseUrl.replace(/^http:\/\//i, 'ws://').replace(/^https:\/\//i, 'wss://');
+    const trimmed = url.replace(/\/+$/, '');
+    return `${trimmed}/websocket`;
+}
+/**
+ * Track an order until all outputs are finalized via the SilentSwap WebSocket API.
+ * Uses the global WebSocket (available in Node 18+ and browsers).
+ *
+ * @param orderId - Base58 order ID returned when placing the order
+ * @param viewingAuth - Viewing authorization (Base58) from the facilitator group
+ * @param options - Optional wsUrl, timeoutMs, and onStatus callback
+ * @returns Final order status when all outputs are FINALIZED
+ * @throws Error on WebSocket error, invalid response, or timeout
+ */
+export function trackOrderViaWebSocket(orderId, viewingAuth, options = {}) {
+    const wsUrl = options.wsUrl ?? DEFAULT_WS_URL;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const onStatus = options.onStatus;
+    return new Promise((resolve, reject) => {
+        if (typeof WebSocket === 'undefined') {
+            reject(new Error('WebSocket is not available. Use Node 18+ or a browser.'));
+            return;
+        }
+        const ws = new WebSocket(wsUrl);
+        let requestId = 0;
+        let finalStatus = null;
+        let heartbeatInterval;
+        const cleanup = () => {
+            if (heartbeatInterval) {
+                clearInterval(heartbeatInterval);
+                heartbeatInterval = undefined;
+            }
+            try {
+                if (ws.readyState === 1)
+                    ws.close();
+            }
+            catch {
+                // ignore
+            }
+        };
+        const tryResolve = () => {
+            if (finalStatus?.outputs?.every((o) => o.stage === STAGE_FINALIZED)) {
+                cleanup();
+                resolve(finalStatus);
+            }
+        };
+        ws.onopen = () => {
+            ws.send(JSON.stringify({
+                jsonrpc: '2.0',
+                id: requestId++,
+                method: 'connect',
+                params: { auth: { orderId, viewingAuth } },
+            }));
+            heartbeatInterval = setInterval(() => {
+                if (ws.readyState === 1) {
+                    const withPing = ws;
+                    try {
+                        withPing.ping?.();
+                    }
+                    catch {
+                        // ignore (browser WebSocket has no ping)
+                    }
+                }
+            }, 30000);
+        };
+        ws.onmessage = (event) => {
+            try {
+                const msg = JSON.parse(typeof event.data === 'string' ? event.data : String(event.data));
+                if (msg.error) {
+                    if (msg.error.code === -32000)
+                        return; // order not found yet
+                    cleanup();
+                    reject(new Error(msg.error.message ?? 'WebSocket error'));
+                    return;
+                }
+                if (msg.result) {
+                    if (msg.result.priority) {
+                        finalStatus = msg.result;
+                        onStatus?.({ type: 'deposit', data: { orderId: finalStatus.deposit?.orderId, amount: finalStatus.deposit?.amount } });
+                        tryResolve();
+                    }
+                    else if (msg.result.type) {
+                        const update = msg.result;
+                        onStatus?.(update);
+                        if (update.type === 'stage' && update.data.stage === STAGE_FINALIZED && finalStatus?.outputs?.[update.data.index ?? -1]) {
+                            finalStatus.outputs[update.data.index].stage = STAGE_FINALIZED;
+                            tryResolve();
+                        }
+                    }
+                }
+            }
+            catch {
+                // ignore parse errors
+            }
+        };
+        ws.onerror = (event) => {
+            cleanup();
+            reject(new Error('WebSocket error'));
+        };
+        ws.onclose = () => {
+            cleanup();
+            if (finalStatus)
+                resolve(finalStatus);
+        };
+        setTimeout(() => {
+            if (finalStatus) {
+                cleanup();
+                resolve(finalStatus);
+            }
+            else {
+                cleanup();
+                reject(new Error('Order tracking timeout'));
+            }
+        }, timeoutMs);
+    });
+}

package/dist/swap-executor.d.ts

@@ -5,6 +5,14 @@
  * This module provides a simple interface for integrators to execute swaps without
  * needing to understand the underlying protocol details.
  *
+ * **Recovery (refund / prove delivery):** Save `result.viewingAuth` and the order ID
+ * for tracking, refund, and recovery. The mnemonic used for the facilitator group can
+ * be derived from the same entropy that was used to create the group: use
+ * `exportSecretMnemonicFromEntropy(entropy)` from this package. Recovery paths are
+ * BIP-44 paths of the form `m/44'/${coinType}'/${accountIndex}'/0/${addressIndex}`,
+ * built from the group's exported public keys (skip coin type `'*'`). See the docs
+ * "Save auth & order ID (refund & recovery)" for full details.
+ *
  * @example
  * ```typescript
  * import { executeSolanaSwap, createSwapAccounts } from '@silentswap/sdk';
@@ -24,6 +32,7 @@
  * });
  *
  * console.log('Order ID:', result.orderId);
+ * console.log('Viewing auth (save for tracking/refund/recovery):', result.viewingAuth);
  * ```
  */
 import type { Caip19 } from './types/core.js';
@@ -90,6 +99,27 @@ export interface SwapResult {
     usdcAmount: string;
     /** Actual source amount used (may differ due to bridge optimization) */
     actualSourceAmount: string;
+    /**
+     * Viewing auth (Base58 EVM address of the facilitator group's viewer) for this order.
+     * Save it together with the order ID to track the order, check refund eligibility, or run
+     * recovery flows.
+     */
+    viewingAuth: string;
+    /**
+     * Recovery data for refund/recovery: mnemonic (24 words) and BIP-44 derivation paths
+     * for the facilitator group. Store securely; do not log or commit.
+     */
+    recoveryData: {
+        mnemonic: string;
+        recoveryPaths: string[];
+    };
+    /** Wallets used for this swap: EVM signer (refundee) and Solana depositor */
+    usedWallet: {
+        /** EVM address used for auth and as refundee */
+        evmAddress: `0x${string}`;
+        /** Solana public key (base58) used for the deposit transaction */
+        solanaPublicKey: string;
+    };
 }
 /**
  * EVM account for signing

package/dist/swap-executor.js

@@ -5,6 +5,14 @@
  * This module provides a simple interface for integrators to execute swaps without
  * needing to understand the underlying protocol details.
  *
+ * **Recovery (refund / prove delivery):** Save `result.viewingAuth` and the order ID
+ * for tracking, refund, and recovery. The mnemonic used for the facilitator group can
+ * be derived from the same entropy that was used to create the group: use
+ * `exportSecretMnemonicFromEntropy(entropy)` from this package. Recovery paths are
+ * BIP-44 paths of the form `m/44'/${coinType}'/${accountIndex}'/0/${addressIndex}`,
+ * built from the group's exported public keys (skip coin type `'*'`). See the docs
+ * "Save auth & order ID (refund & recovery)" for full details.
+ *
  * @example
  * ```typescript
  * import { executeSolanaSwap, createSwapAccounts } from '@silentswap/sdk';
@@ -24,14 +32,15 @@
  * });
  *
  * console.log('Order ID:', result.orderId);
+ * console.log('Viewing auth (save for tracking/refund/recovery):', result.viewingAuth);
  * ```
  */
 import { encodeFunctionData, erc20Abi } from 'viem';
 import { createSilentSwapClient } from './client.js';
 import { createSignInMessage, createEip712DocForWalletGeneration } from './sdk.js';
-import { createHdFacilitatorGroupFromEntropy } from './hd-facilitator-group.js';
+import { createHdFacilitatorGroupFromEntropy, exportSecretMnemonicFromEntropy, } from './hd-facilitator-group.js';
 import { queryDepositCount } from './wallet.js';
-import { hexToBytes } from './encoding.js';
+import { hexToBytes, hexToBase58 } from './encoding.js';
 import { quoteResponseToEip712Document, DeliveryMethod, FacilitatorKeyType, PublicKeyArgGroups } from './order.js';
 import { solveOptimalUsdcAmount, fetchRelayQuote, getRelayStatus } from './bridge.js';
 import { ENVIRONMENT, N_RELAY_CHAIN_ID_SOLANA, NI_CHAIN_ID_AVALANCHE, SB58_ADDR_SOL_PROGRAM_SYSTEM, SB58_CHAIN_ID_SOLANA_MAINNET, S0X_ADDR_USDC_AVALANCHE, } from './constants.js';
@@ -491,12 +500,32 @@ export async function executeSolanaSwap(config) {
             });
         }
     }
+    // Derive viewing auth (viewer EVM address as Base58) for tracking, refund, and recovery
+    const viewer = await facilitatorGroup.viewer();
+    const viewerEvmSigner = await viewer.evmSigner();
+    const viewingAuth = hexToBase58(viewerEvmSigner.address);
+    // Build recovery data (mnemonic + paths) for refund/recovery
+    const groupPublicKeysForRecovery = await facilitatorGroup.exportPublicKeys(1, [...PublicKeyArgGroups.GENERIC]);
+    const recoveryPaths = [];
+    for (const pk of groupPublicKeysForRecovery[0] ?? []) {
+        if (pk.coinType === '*')
+            continue;
+        recoveryPaths.push(`m/44'/${pk.coinType}'/${depositCount}'/0/0`);
+    }
+    const mnemonic = (await exportSecretMnemonicFromEntropy(hexToBytes(entropy))).toString();
+    const recoveryData = { mnemonic, recoveryPaths };
     return {
         orderId,
         quoteId: quoteResponse.quoteId,
         depositTxHash: txHash,
         usdcAmount: bridgeResult.usdcAmountOut.toString(),
         actualSourceAmount: bridgeResult.actualAmountIn.toString(),
+        viewingAuth,
+        recoveryData,
+        usedWallet: {
+            evmAddress: accounts.evm.address,
+            solanaPublicKey: accounts.solana.publicKey,
+        },
     };
 }
 // ============================================================================

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@silentswap/sdk",
   "type": "module",
-  "version": "0.0.76",
+  "version": "0.0.78",
   "license": "MIT",
   "main": "dist/index.js",
   "files": [