@velumx/sdk 2.0.1 → 2.2.0

package/README.md

@@ -113,13 +113,28 @@ const result = await openContractCall({
 ### Fee Calculation
 
 ```
-Fee in USDCx = (Gas Cost in STX × STX/USD Rate × 1.08) / USDC/USD Rate
+Fee in any SIP-010 token = (Gas Cost in STX × STX/USD Rate × 1.08) / Token/USD Rate
 
-Example:
+Example with USDCx:
 - Gas: 100,000 units = 1 STX
 - STX/USD: $0.50
+- USDC/USD: $1.00
 - Markup: 8%
-- Fee: 1 × $0.50 × 1.08 = $0.54 = 0.54 USDCx
+- Fee: 1 × $0.50 × 1.08 / $1.00 = 0.54 USDCx
+
+Example with sBTC:
+- Gas: 100,000 units = 1 STX
+- STX/USD: $0.50
+- BTC/USD: $45,000
+- Markup: 8%
+- Fee: 1 × $0.50 × 1.08 / $45,000 = 0.000012 BTC (1,200 sats)
+
+Example with ALEX:
+- Gas: 100,000 units = 1 STX
+- STX/USD: $0.50
+- ALEX/USD: $0.10
+- Markup: 8%
+- Fee: 1 × $0.50 × 1.08 / $0.10 = 5.4 ALEX
 ```
 
 ## API Reference
@@ -368,6 +383,85 @@ async function customGaslessTransaction() {
 }
 ```
 
+### 4. Using Different Fee Tokens
+
+Pay fees in sBTC, ALEX, or any SIP-010 token.
+
+```typescript
+async function gaslessWithSBTC(amount: string) {
+  const velumx = getVelumXClient();
+  
+  // 1. Estimate fee (returns USDCx equivalent)
+  const estimate = await velumx.estimateFee({
+    estimatedGas: 100000
+  });
+  
+  // 2. Convert fee to sBTC (example: 0.54 USDCx → 0.000012 BTC)
+  const feeInSBTC = convertToSBTC(estimate.maxFeeUSDCx);
+  
+  // 3. Execute with sBTC as fee token
+  const result = await openContractCall({
+    contractAddress: 'STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P',
+    contractName: 'simple-paymaster-v1',
+    functionName: 'bridge-gasless',
+    functionArgs: [
+      Cl.uint(parseUnits(amount, 6)),
+      Cl.buffer(recipientBytes),
+      Cl.uint(feeInSBTC),  // Fee in sBTC
+      Cl.principal('STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P'),
+      Cl.principal('SM3KNVZS30WM7F89SXKVVFY4SN9RMPZZ9FX929N0V.sbtc')  // sBTC token
+    ],
+    sponsored: true,
+    network: 'testnet',
+    onFinish: async (data) => {
+      const tx = await velumx.submitRawTransaction(data.txRaw);
+      console.log(`Transaction: ${tx.txid}`);
+    }
+  });
+}
+
+// Helper: Convert USDCx fee to sBTC
+function convertToSBTC(feeInUSDCx: string): string {
+  // Example conversion (fetch real rates from API)
+  const usdcAmount = Number(feeInUSDCx) / 1_000_000; // 0.54 USDC
+  const btcPrice = 45000; // $45,000 per BTC
+  const btcAmount = usdcAmount / btcPrice; // 0.000012 BTC
+  const satoshis = Math.ceil(btcAmount * 100_000_000); // 1,200 sats
+  return satoshis.toString();
+}
+
+// Using ALEX token
+async function gaslessWithALEX(amount: string) {
+  const velumx = getVelumXClient();
+  
+  const estimate = await velumx.estimateFee({
+    estimatedGas: 100000
+  });
+  
+  // Convert to ALEX (example: 0.54 USDCx → 5.4 ALEX)
+  const feeInALEX = convertToALEX(estimate.maxFeeUSDCx);
+  
+  const result = await openContractCall({
+    contractAddress: 'STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P',
+    contractName: 'simple-paymaster-v1',
+    functionName: 'bridge-gasless',
+    functionArgs: [
+      Cl.uint(parseUnits(amount, 6)),
+      Cl.buffer(recipientBytes),
+      Cl.uint(feeInALEX),  // Fee in ALEX
+      Cl.principal('STKYNF473GQ1V0WWCF24TV7ZR1WYAKTC79V25E3P'),
+      Cl.principal('ALEX_TOKEN_ADDRESS')  // ALEX token
+    ],
+    sponsored: true,
+    network: 'testnet',
+    onFinish: async (data) => {
+      const tx = await velumx.submitRawTransaction(data.txRaw);
+      console.log(`Transaction: ${tx.txid}`);
+    }
+  });
+}
+```
+
 ## Smart Contract Integration
 
 To make your contract gasless-compatible, accept a fee parameter and transfer it to the relayer:
@@ -393,6 +487,55 @@ To make your contract gasless-compatible, accept a fee parameter and transfer it
 
 ## Configuration
 
+### Supported Fee Tokens
+
+VelumX accepts ANY SIP-010 token for gas fees. The paymaster contract uses the `<sip-010-trait>` parameter for universal compatibility.
+
+**Popular Tokens:**
+
+| Token | Contract Address | Decimals | Use Case |
+|-------|-----------------|----------|----------|
+| USDCx | `ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx` | 6 | Stablecoin fees |
+| sBTC | `SM3KNVZS30WM7F89SXKVVFY4SN9RMPZZ9FX929N0V.sbtc` | 8 | Bitcoin fees |
+| ALEX | `ALEX_TOKEN_ADDRESS` | 6 | DeFi token fees |
+| STX | Native | 6 | Native token fees |
+
+**Exchange Rate Calculation:**
+
+```typescript
+// Fetch real-time exchange rates
+async function calculateFeeInToken(
+  feeInUSDCx: string,
+  targetToken: 'sBTC' | 'ALEX' | 'STX'
+): Promise<string> {
+  const usdcAmount = Number(feeInUSDCx) / 1_000_000;
+  
+  // Fetch rates from price oracle or API
+  const rates = await fetchExchangeRates();
+  
+  switch (targetToken) {
+    case 'sBTC':
+      const btcAmount = usdcAmount / rates.BTC_USD;
+      return Math.ceil(btcAmount * 100_000_000).toString(); // Convert to satoshis
+    
+    case 'ALEX':
+      const alexAmount = usdcAmount / rates.ALEX_USD;
+      return Math.ceil(alexAmount * 1_000_000).toString(); // Convert to micro-ALEX
+    
+    case 'STX':
+      const stxAmount = usdcAmount / rates.STX_USD;
+      return Math.ceil(stxAmount * 1_000_000).toString(); // Convert to micro-STX
+    
+    default:
+      return feeInUSDCx;
+  }
+}
+
+// Example usage
+const estimate = await velumx.estimateFee({ estimatedGas: 100000 });
+const feeInSBTC = await calculateFeeInToken(estimate.maxFeeUSDCx, 'sBTC');
+```
+
 ### Environment Variables
 
 ```bash
@@ -513,10 +656,13 @@ Status: https://sgal-relayer.onrender.com/api/v1/health
 ## FAQ
 
 ### Q: Do users need STX?
-**A:** No! Users only need USDCx. The relayer pays STX fees.
+**A:** No! Users only need any SIP-010 token (USDCx, sBTC, ALEX, etc.). The relayer pays STX fees.
+
+### Q: What tokens can I use for fees?
+**A:** Any SIP-010 compliant token! Popular options include USDCx, sBTC, ALEX, and STX. The paymaster contract uses the `<sip-010-trait>` parameter for universal compatibility.
 
 ### Q: How much does it cost?
-**A:** Fees are calculated in real-time based on STX/USD rates with an 8% markup. Typically 0.001-0.01 USDCx per transaction.
+**A:** Fees are calculated in real-time based on STX/USD rates with an 8% markup. Typically 0.001-0.01 USDCx (or equivalent in other tokens) per transaction.
 
 ### Q: Is it secure?
 **A:** Yes! Uses Stacks' native sponsored transaction feature. No smart wallet complexity.

package/dist/VelumXClient.d.ts

@@ -1,10 +1,10 @@
-import { SignedIntent, NetworkConfig } from './types';
+import { SignedIntent, NetworkConfig, SponsorshipOptions } from './types';
 export declare class VelumXClient {
     private config;
     private relayerUrl;
     constructor(config: NetworkConfig);
     /**
-     * Get a fee estimation from the SGAL relayer for a specific intent
+     * Get a fee estimation from the relayer for a specific intent
      */
     estimateFee(intent: any): Promise<{
         maxFeeUSDCx: string;
@@ -17,10 +17,19 @@ export declare class VelumXClient {
         txid: string;
         status: string;
     }>;
+    /**
+     * [New Recommended Method] Request sponsorship for a Stacks transaction
+     * @param txHex The raw transaction hex
+     * @param options Metadata like developer-reported fee and userId
+     */
+    sponsor(txHex: string, options?: SponsorshipOptions): Promise<{
+        txid: string;
+        status: string;
+    }>;
     /**
      * Submit a raw Stacks transaction hex for native sponsorship
      */
-    submitRawTransaction(txHex: string): Promise<{
+    submitRawTransaction(txHex: string, options?: SponsorshipOptions): Promise<{
         txid: string;
         status: string;
     }>;

package/dist/VelumXClient.js

@@ -3,17 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VelumXClient = void 0;
 class VelumXClient {
     constructor(config) {
+        if (!config.apiKey && !config.paymasterUrl?.includes('/api/velumx/proxy')) {
+            throw new Error("VelumX Client Error: API Key is required. Please obtain your key from the VelumX Developer Dashboard.");
+        }
         this.config = config;
         // Default to a hosted relayer if not provided
         this.relayerUrl = config.paymasterUrl || 'https://relayer.velumx.com/api/v1';
     }
     /**
-     * Get a fee estimation from the SGAL relayer for a specific intent
+     * Get a fee estimation from the relayer for a specific intent
      */
     async estimateFee(intent) {
         try {
             const headers = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
             const response = await fetch(`${this.relayerUrl}/estimate`, {
@@ -38,7 +41,7 @@ class VelumXClient {
     async submitIntent(signedIntent) {
         try {
             const headers = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
             const response = await fetch(`${this.relayerUrl}/sponsor`, {
@@ -57,19 +60,31 @@ class VelumXClient {
             throw error;
         }
     }
+    /**
+     * [New Recommended Method] Request sponsorship for a Stacks transaction
+     * @param txHex The raw transaction hex
+     * @param options Metadata like developer-reported fee and userId
+     */
+    async sponsor(txHex, options) {
+        return this.submitRawTransaction(txHex, options);
+    }
     /**
      * Submit a raw Stacks transaction hex for native sponsorship
      */
-    async submitRawTransaction(txHex) {
+    async submitRawTransaction(txHex, options) {
         try {
             const headers = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
             const response = await fetch(`${this.relayerUrl}/broadcast`, {
                 method: 'POST',
                 headers,
-                body: JSON.stringify({ txHex })
+                body: JSON.stringify({
+                    txHex,
+                    userId: options?.userId,
+                    feeAmount: options?.feeAmount
+                })
             });
             if (!response.ok) {
                 const errData = await response.json().catch(() => ({ error: 'Unknown error' }));

package/dist/types.d.ts

@@ -14,3 +14,7 @@ export interface NetworkConfig {
     paymasterUrl?: string;
     apiKey?: string;
 }
+export interface SponsorshipOptions {
+    userId?: string;
+    feeAmount?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velumx/sdk",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "VelumX Gas Abstraction Layer SDK for dApps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/VelumXClient.ts

@@ -1,22 +1,25 @@
-import { SignedIntent, NetworkConfig } from './types';
+import { SignedIntent, NetworkConfig, SponsorshipOptions } from './types';
 
 export class VelumXClient {
     private config: NetworkConfig;
     private relayerUrl: string;
 
     constructor(config: NetworkConfig) {
+        if (!config.apiKey && !config.paymasterUrl?.includes('/api/velumx/proxy')) {
+            throw new Error("VelumX Client Error: API Key is required. Please obtain your key from the VelumX Developer Dashboard.");
+        }
         this.config = config;
         // Default to a hosted relayer if not provided
         this.relayerUrl = config.paymasterUrl || 'https://relayer.velumx.com/api/v1';
     }
 
     /**
-     * Get a fee estimation from the SGAL relayer for a specific intent
+     * Get a fee estimation from the relayer for a specific intent
      */
     public async estimateFee(intent: any): Promise<{ maxFeeUSDCx: string, estimatedGas: number }> {
         try {
             const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
 
@@ -44,7 +47,7 @@ export class VelumXClient {
     public async submitIntent(signedIntent: SignedIntent): Promise<{ txid: string, status: string }> {
         try {
             const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
 
@@ -66,20 +69,33 @@ export class VelumXClient {
         }
     }
 
+    /**
+     * [New Recommended Method] Request sponsorship for a Stacks transaction
+     * @param txHex The raw transaction hex
+     * @param options Metadata like developer-reported fee and userId
+     */
+    public async sponsor(txHex: string, options?: SponsorshipOptions): Promise<{ txid: string, status: string }> {
+        return this.submitRawTransaction(txHex, options);
+    }
+
     /**
      * Submit a raw Stacks transaction hex for native sponsorship
      */
-    public async submitRawTransaction(txHex: string): Promise<{ txid: string, status: string }> {
+    public async submitRawTransaction(txHex: string, options?: SponsorshipOptions): Promise<{ txid: string, status: string }> {
         try {
             const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-            if (this.config.apiKey) {
+            if (this.config.apiKey && this.config.apiKey !== 'proxied') {
                 headers['x-api-key'] = this.config.apiKey;
             }
 
             const response = await fetch(`${this.relayerUrl}/broadcast`, {
                 method: 'POST',
                 headers,
-                body: JSON.stringify({ txHex })
+                body: JSON.stringify({ 
+                    txHex,
+                    userId: options?.userId,
+                    feeAmount: options?.feeAmount
+                })
             });
 
             if (!response.ok) {

package/src/types.ts

@@ -15,6 +15,11 @@ export interface SignedIntent extends WalletIntent {
 export interface NetworkConfig {
     coreApiUrl: string;
     network: 'mainnet' | 'testnet' | 'devnet';
-    paymasterUrl?: string; // URL for the SGAL relayer service
-    apiKey?: string; // SGAL API Key
+    paymasterUrl?: string; // URL for the VelumX relayer service
+    apiKey?: string; // VelumX API Key
+}
+
+export interface SponsorshipOptions {
+    userId?: string;
+    feeAmount?: string;
 }