@velumx/sdk 1.3.0 → 2.0.0

package/README.md

@@ -0,0 +1,306 @@
+# VelumX SDK
+
+The first Paymaster infrastructure on Stacks blockchain. Enable gasless transactions in your dApp - users pay gas fees in USDCx instead of STX.
+
+## 🚀 Features
+
+- **Gasless Transactions**: Users pay fees in USDCx, not STX
+- **Account Abstraction**: Smart Wallet pattern with SIP-018 signing
+- **Simple Integration**: 3 lines of code to add gasless support
+- **Production Ready**: Battle-tested relayer infrastructure
+- **Developer Friendly**: TypeScript SDK with full type safety
+
+## 📦 Installation
+
+```bash
+npm install @velumx/sdk
+```
+
+## 🔧 Quick Start
+
+### 1. Get API Key
+
+Register your dApp at [dashboard.velumx.com](https://dashboard.velumx.com) to get your API key.
+
+### 2. Initialize Client
+
+```typescript
+import { VelumXClient } from '@velumx/sdk';
+
+const velumx = new VelumXClient({
+  coreApiUrl: 'https://api.testnet.hiro.so',
+  network: 'testnet',
+  paymasterUrl: 'https://relayer.velumx.com/api/v1',
+  apiKey: 'your-api-key-here'
+});
+```
+
+### 3. Estimate Fee
+
+```typescript
+const estimate = await velumx.estimateFee({
+  estimatedGas: 100000
+});
+
+console.log(`Fee: ${estimate.maxFeeUSDCx} micro-USDCx`);
+```
+
+### 4. Submit Gasless Transaction
+
+```typescript
+import { tupleCV, uintCV, bufferCV, serializeCV } from '@stacks/transactions';
+
+// Create your transaction payload
+const payload = tupleCV({
+  amount: uintCV(1000000), // 1 USDCx
+  recipient: bufferCV(recipientBytes)
+});
+
+// Create intent
+const intent = {
+  target: 'ST...CONTRACT.paymaster-module-v10',
+  payload: serializeCV(payload),
+  maxFeeUSDCx: estimate.maxFeeUSDCx,
+  nonce: currentNonce
+};
+
+// Sign with user's wallet (SIP-018)
+const signature = await signWithWallet(intent);
+
+// Submit to relayer
+const result = await velumx.submitIntent({
+  ...intent,
+  signature
+});
+
+console.log(`Transaction ID: ${result.txid}`);
+```
+
+## 📚 API Reference
+
+### VelumXClient
+
+#### Constructor
+
+```typescript
+new VelumXClient(config: NetworkConfig)
+```
+
+**NetworkConfig:**
+- `coreApiUrl`: Stacks API URL (mainnet/testnet)
+- `network`: 'mainnet' | 'testnet' | 'devnet'
+- `paymasterUrl`: VelumX relayer URL
+- `apiKey`: Your dApp API key (optional for testnet)
+
+#### Methods
+
+##### estimateFee()
+
+```typescript
+estimateFee(intent: { estimatedGas: number }): Promise<{
+  maxFeeUSDCx: string;
+  estimatedGas: number;
+}>
+```
+
+Get fee estimate in USDCx for a transaction.
+
+##### submitIntent()
+
+```typescript
+submitIntent(signedIntent: SignedIntent): Promise<{
+  txid: string;
+  status: string;
+}>
+```
+
+Submit a signed intent for gasless execution.
+
+**SignedIntent:**
+- `target`: Contract principal to call
+- `payload`: Hex-encoded transaction payload
+- `maxFeeUSDCx`: Maximum fee in micro-USDCx
+- `nonce`: Smart Wallet nonce
+- `signature`: SIP-018 signature
+
+##### submitRawTransaction()
+
+```typescript
+submitRawTransaction(txHex: string): Promise<{
+  txid: string;
+  status: string;
+}>
+```
+
+Submit a raw Stacks transaction for sponsorship.
+
+## 🎯 Use Cases
+
+### Bridge Transactions
+
+```typescript
+// User bridges USDC from Ethereum to Stacks
+// Pays gas fee in USDCx instead of STX
+const payload = tupleCV({
+  amount: uintCV(5000000), // 5 USDCx
+  fee: uintCV(250000),     // 0.25 USDCx fee
+  recipient: bufferCV(ethAddressBytes)
+});
+
+const result = await velumx.submitIntent({
+  target: 'ST...ADMIN.paymaster-module-v10',
+  payload: serializeCV(payload),
+  maxFeeUSDCx: '250000',
+  nonce: 0,
+  signature: userSignature
+});
+```
+
+### Token Swaps
+
+```typescript
+// User swaps tokens without needing STX
+const payload = tupleCV({
+  tokenIn: principalCV('ST...TOKEN-A'),
+  tokenOut: principalCV('ST...TOKEN-B'),
+  amountIn: uintCV(1000000),
+  minOut: uintCV(950000),
+  fee: uintCV(200000)
+});
+
+const result = await velumx.submitIntent({
+  target: 'ST...ADMIN.swap-contract',
+  payload: serializeCV(payload),
+  maxFeeUSDCx: '200000',
+  nonce: 1,
+  signature: userSignature
+});
+```
+
+### NFT Minting
+
+```typescript
+// User mints NFT paying gas in USDCx
+const payload = tupleCV({
+  recipient: principalCV(userAddress),
+  tokenId: uintCV(42),
+  fee: uintCV(300000)
+});
+
+const result = await velumx.submitIntent({
+  target: 'ST...ADMIN.nft-contract',
+  payload: serializeCV(payload),
+  maxFeeUSDCx: '300000',
+  nonce: 2,
+  signature: userSignature
+});
+```
+
+## 🔐 Smart Wallet Setup
+
+Users need a Smart Wallet to use gasless transactions. The SDK handles this automatically:
+
+```typescript
+import { getSmartWalletManager } from '@velumx/sdk';
+
+const manager = getSmartWalletManager();
+
+// Check if user has Smart Wallet
+const hasWallet = await manager.hasSmartWallet(userAddress);
+
+if (!hasWallet) {
+  // Auto-register (one-time setup)
+  const result = await manager.ensureSmartWallet(userAddress);
+  console.log(`Smart Wallet: ${result}`);
+}
+```
+
+## 💰 Fee Structure
+
+- **Base Fee**: Actual STX gas cost converted to USDCx
+- **Markup**: 8% (configurable by relayer)
+- **Example**: 0.005 STX gas = ~$0.0025 = 0.0025 USDCx + 8% = 0.0027 USDCx
+
+## 🌐 Network Support
+
+### Testnet
+- Relayer: `https://relayer.velumx.com/api/v1`
+- Stacks API: `https://api.testnet.hiro.so`
+- Free for development (no API key required)
+
+### Mainnet
+- Relayer: `https://mainnet-relayer.velumx.com/api/v1`
+- Stacks API: `https://api.mainnet.hiro.so`
+- Requires API key from dashboard
+
+## 🛠️ Advanced Usage
+
+### Custom Fee Calculation
+
+```typescript
+// Get exchange rates
+const rates = await velumx.getExchangeRates();
+console.log(`STX/USD: ${rates.stxToUsd}`);
+
+// Calculate custom fee
+const gasInStx = 0.005;
+const gasInUsd = gasInStx * rates.stxToUsd;
+const feeInUsdcx = gasInUsd * 1.08; // 8% markup
+```
+
+### Transaction Monitoring
+
+```typescript
+// Submit transaction
+const result = await velumx.submitIntent(signedIntent);
+
+// Monitor status
+const status = await fetch(
+  `https://api.testnet.hiro.so/extended/v1/tx/${result.txid}`
+);
+
+const data = await status.json();
+console.log(`Status: ${data.tx_status}`);
+```
+
+### Error Handling
+
+```typescript
+try {
+  const result = await velumx.submitIntent(signedIntent);
+} catch (error) {
+  if (error.message.includes('insufficient balance')) {
+    console.error('User needs more USDCx for fees');
+  } else if (error.message.includes('invalid signature')) {
+    console.error('Signature verification failed');
+  } else {
+    console.error('Transaction failed:', error);
+  }
+}
+```
+
+## 📖 Examples
+
+Check out complete examples:
+- [Bridge dApp](../examples/bridge)
+- [DEX Integration](../examples/swap)
+- [NFT Marketplace](../examples/nft)
+
+## 🤝 Support
+
+- **Documentation**: [docs.velumx.com](https://docs.velumx.com)
+- **Dashboard**: [dashboard.velumx.com](https://dashboard.velumx.com)
+- **Discord**: [discord.gg/velumx](https://discord.gg/velumx)
+- **Email**: support@velumx.com
+
+## 📄 License
+
+MIT License - see [LICENSE](./LICENSE) for details
+
+## 🎉 Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+---
+
+Built with ❤️ by the VelumX team

package/dist/IntentBuilder.d.ts

@@ -10,7 +10,7 @@ export declare class IntentBuilder {
     private getDomain;
     /**
      * Formats the intent into a Clarity Tuple for signing
-     * Structure matches the Smart Wallet v4 expectation
+     * Structure matches the Smart Wallet v10 expectation
      */
     private formatIntentMessage;
     /**

package/dist/IntentBuilder.js

@@ -20,7 +20,7 @@ class IntentBuilder {
     }
     /**
      * Formats the intent into a Clarity Tuple for signing
-     * Structure matches the Smart Wallet v4 expectation
+     * Structure matches the Smart Wallet v10 expectation
      */
     formatIntentMessage(intent) {
         return (0, transactions_1.tupleCV)({

package/dist/SimplePaymaster.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Simple Paymaster SDK
+ * Simplified gasless transactions using Stacks-native sponsored transactions
+ */
+export interface SimplePaymasterConfig {
+    network: 'mainnet' | 'testnet';
+    paymasterContract: string;
+    relayerAddress: string;
+    usdcxContract: string;
+}
+export interface BridgeParams {
+    amount: string;
+    recipient: string;
+    feeUsdcx: string;
+    onFinish?: (data: any) => void;
+    onCancel?: () => void;
+}
+export interface SwapParams {
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: string;
+    minOut: string;
+    feeUsdcx: string;
+    onFinish?: (data: any) => void;
+    onCancel?: () => void;
+}
+export declare class SimplePaymaster {
+    private config;
+    constructor(config: SimplePaymasterConfig);
+    /**
+     * Execute gasless bridge withdrawal (Stacks → Ethereum)
+     */
+    bridgeGasless(params: BridgeParams): Promise<void>;
+    /**
+     * Execute gasless swap
+     */
+    swapGasless(params: SwapParams): Promise<void>;
+    /**
+     * Estimate fee for gasless transaction
+     */
+    estimateFee(estimatedGas?: number): Promise<{
+        feeUsdcx: string;
+    }>;
+    /**
+     * Encode Ethereum address to bytes32 for Stacks contract
+     */
+    private encodeEthereumAddress;
+}

package/dist/SimplePaymaster.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Simple Paymaster SDK
+ * Simplified gasless transactions using Stacks-native sponsored transactions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimplePaymaster = void 0;
+const connect_1 = require("@stacks/connect");
+const transactions_1 = require("@stacks/transactions");
+class SimplePaymaster {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Execute gasless bridge withdrawal (Stacks → Ethereum)
+     */
+    async bridgeGasless(params) {
+        const [contractAddress, contractName] = this.config.paymasterContract.split('.');
+        // Encode Ethereum address to bytes32
+        const recipientBytes = this.encodeEthereumAddress(params.recipient);
+        const functionArgs = [
+            (0, transactions_1.uintCV)(params.amount),
+            (0, transactions_1.bufferCV)(recipientBytes),
+            (0, transactions_1.uintCV)(params.feeUsdcx),
+            (0, transactions_1.principalCV)(this.config.relayerAddress),
+            (0, transactions_1.contractPrincipalCV)(this.config.usdcxContract.split('.')[0], this.config.usdcxContract.split('.')[1])
+        ];
+        await (0, connect_1.openContractCall)({
+            contractAddress,
+            contractName,
+            functionName: 'bridge-gasless',
+            functionArgs,
+            network: this.config.network,
+            sponsored: true,
+            postConditionMode: transactions_1.PostConditionMode.Allow,
+            onFinish: params.onFinish || (() => { }),
+            onCancel: params.onCancel || (() => { }),
+        });
+    }
+    /**
+     * Execute gasless swap
+     */
+    async swapGasless(params) {
+        const [contractAddress, contractName] = this.config.paymasterContract.split('.');
+        const functionArgs = [
+            (0, transactions_1.principalCV)(params.tokenIn),
+            (0, transactions_1.principalCV)(params.tokenOut),
+            (0, transactions_1.uintCV)(params.amountIn),
+            (0, transactions_1.uintCV)(params.minOut),
+            (0, transactions_1.uintCV)(params.feeUsdcx),
+            (0, transactions_1.principalCV)(this.config.relayerAddress),
+            (0, transactions_1.contractPrincipalCV)(this.config.usdcxContract.split('.')[0], this.config.usdcxContract.split('.')[1])
+        ];
+        await (0, connect_1.openContractCall)({
+            contractAddress,
+            contractName,
+            functionName: 'swap-gasless',
+            functionArgs,
+            network: this.config.network,
+            sponsored: true,
+            postConditionMode: transactions_1.PostConditionMode.Allow,
+            onFinish: params.onFinish || (() => { }),
+            onCancel: params.onCancel || (() => { }),
+        });
+    }
+    /**
+     * Estimate fee for gasless transaction
+     */
+    async estimateFee(estimatedGas = 100000) {
+        // Simple fee calculation: ~0.25 USDCx per transaction
+        // In production, this would call the relayer API
+        return {
+            feeUsdcx: '250000' // 0.25 USDCx
+        };
+    }
+    /**
+     * Encode Ethereum address to bytes32 for Stacks contract
+     */
+    encodeEthereumAddress(address) {
+        const hex = address.startsWith('0x') ? address.slice(2) : address;
+        const paddedHex = hex.padStart(64, '0');
+        const bytes = new Uint8Array(32);
+        for (let i = 0; i < 32; i++) {
+            bytes[i] = parseInt(paddedHex.substring(i * 2, i * 2 + 2), 16);
+        }
+        return bytes;
+    }
+}
+exports.SimplePaymaster = SimplePaymaster;

package/dist/VelumXClient.js

@@ -22,7 +22,7 @@ class VelumXClient {
                 body: JSON.stringify({ intent })
             });
             if (!response.ok) {
-                const errData = await response.json().catch(() => ({}));
+                const errData = await response.json().catch(() => ({ error: 'Unknown error' }));
                 throw new Error(`Fee estimation failed: ${errData.error || errData.message || response.statusText}`);
             }
             return await response.json();
@@ -47,7 +47,7 @@ class VelumXClient {
                 body: JSON.stringify({ intent: signedIntent })
             });
             if (!response.ok) {
-                const errData = await response.json().catch(() => ({}));
+                const errData = await response.json().catch(() => ({ error: 'Unknown error' }));
                 throw new Error(`Intent sponsorship failed: ${errData.error || errData.message || response.statusText}`);
             }
             return await response.json();
@@ -72,7 +72,7 @@ class VelumXClient {
                 body: JSON.stringify({ txHex })
             });
             if (!response.ok) {
-                const errData = await response.json().catch(() => ({}));
+                const errData = await response.json().catch(() => ({ error: 'Unknown error' }));
                 throw new Error(`Transaction broadcast failed: ${errData.error || errData.message || response.statusText}`);
             }
             return await response.json();

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './IntentBuilder';
 export * from './VelumXClient';
+export * from './SimplePaymaster';

package/dist/index.js

@@ -17,7 +17,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./IntentBuilder"), exports);
 __exportStar(require("./VelumXClient"), exports);
+__exportStar(require("./SimplePaymaster"), exports);
 // Core entrypoint for the @velumx/sdk
 // Example Usage:
 // const client = new VelumXClient({ network: 'testnet' });
-// const intentBuilder = new IntentBuilder();
+// const paymaster = new SimplePaymaster({ network: 'testnet', ... });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velumx/sdk",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "VelumX Gas Abstraction Layer SDK for dApps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,6 +24,7 @@
   "license": "MIT",
   "dependencies": {
     "@stacks/common": "^7.3.1",
+    "@stacks/connect": "^7.10.0",
     "@stacks/network": "^7.3.1",
     "@stacks/transactions": "^7.3.1"
   },

package/src/IntentBuilder.ts

@@ -33,7 +33,7 @@ export class IntentBuilder {
 
     /**
      * Formats the intent into a Clarity Tuple for signing
-     * Structure matches the Smart Wallet v4 expectation
+     * Structure matches the Smart Wallet v10 expectation
      */
     private formatIntentMessage(intent: WalletIntent) {
         return tupleCV({

package/src/SimplePaymaster.ts

@@ -0,0 +1,130 @@
+/**
+ * Simple Paymaster SDK
+ * Simplified gasless transactions using Stacks-native sponsored transactions
+ */
+
+import { openContractCall } from '@stacks/connect';
+import { 
+    uintCV, 
+    bufferCV, 
+    principalCV, 
+    contractPrincipalCV,
+    ClarityValue,
+    PostConditionMode
+} from '@stacks/transactions';
+
+export interface SimplePaymasterConfig {
+    network: 'mainnet' | 'testnet';
+    paymasterContract: string; // e.g., 'DEPLOYER.simple-paymaster-v1'
+    relayerAddress: string; // e.g., 'STKY...25E3P'
+    usdcxContract: string; // e.g., 'ST1P...PGZGM.usdcx'
+}
+
+export interface BridgeParams {
+    amount: string; // Amount in micro units (e.g., "10000000" for 10 USDCx)
+    recipient: string; // Ethereum address (0x...)
+    feeUsdcx: string; // Fee in micro units (e.g., "250000" for 0.25 USDCx)
+    onFinish?: (data: any) => void;
+    onCancel?: () => void;
+}
+
+export interface SwapParams {
+    tokenIn: string; // Contract principal
+    tokenOut: string; // Contract principal
+    amountIn: string; // Amount in micro units
+    minOut: string; // Minimum output in micro units
+    feeUsdcx: string; // Fee in micro units
+    onFinish?: (data: any) => void;
+    onCancel?: () => void;
+}
+
+export class SimplePaymaster {
+    private config: SimplePaymasterConfig;
+
+    constructor(config: SimplePaymasterConfig) {
+        this.config = config;
+    }
+
+    /**
+     * Execute gasless bridge withdrawal (Stacks → Ethereum)
+     */
+    async bridgeGasless(params: BridgeParams): Promise<void> {
+        const [contractAddress, contractName] = this.config.paymasterContract.split('.');
+        
+        // Encode Ethereum address to bytes32
+        const recipientBytes = this.encodeEthereumAddress(params.recipient);
+
+        const functionArgs: ClarityValue[] = [
+            uintCV(params.amount),
+            bufferCV(recipientBytes),
+            uintCV(params.feeUsdcx),
+            principalCV(this.config.relayerAddress),
+            contractPrincipalCV(this.config.usdcxContract.split('.')[0], this.config.usdcxContract.split('.')[1])
+        ];
+
+        await openContractCall({
+            contractAddress,
+            contractName,
+            functionName: 'bridge-gasless',
+            functionArgs,
+            network: this.config.network,
+            sponsored: true,
+            postConditionMode: PostConditionMode.Allow,
+            onFinish: params.onFinish || (() => {}),
+            onCancel: params.onCancel || (() => {}),
+        });
+    }
+
+    /**
+     * Execute gasless swap
+     */
+    async swapGasless(params: SwapParams): Promise<void> {
+        const [contractAddress, contractName] = this.config.paymasterContract.split('.');
+
+        const functionArgs: ClarityValue[] = [
+            principalCV(params.tokenIn),
+            principalCV(params.tokenOut),
+            uintCV(params.amountIn),
+            uintCV(params.minOut),
+            uintCV(params.feeUsdcx),
+            principalCV(this.config.relayerAddress),
+            contractPrincipalCV(this.config.usdcxContract.split('.')[0], this.config.usdcxContract.split('.')[1])
+        ];
+
+        await openContractCall({
+            contractAddress,
+            contractName,
+            functionName: 'swap-gasless',
+            functionArgs,
+            network: this.config.network,
+            sponsored: true,
+            postConditionMode: PostConditionMode.Allow,
+            onFinish: params.onFinish || (() => {}),
+            onCancel: params.onCancel || (() => {}),
+        });
+    }
+
+    /**
+     * Estimate fee for gasless transaction
+     */
+    async estimateFee(estimatedGas: number = 100000): Promise<{ feeUsdcx: string }> {
+        // Simple fee calculation: ~0.25 USDCx per transaction
+        // In production, this would call the relayer API
+        return {
+            feeUsdcx: '250000' // 0.25 USDCx
+        };
+    }
+
+    /**
+     * Encode Ethereum address to bytes32 for Stacks contract
+     */
+    private encodeEthereumAddress(address: string): Uint8Array {
+        const hex = address.startsWith('0x') ? address.slice(2) : address;
+        const paddedHex = hex.padStart(64, '0');
+        const bytes = new Uint8Array(32);
+        for (let i = 0; i < 32; i++) {
+            bytes[i] = parseInt(paddedHex.substring(i * 2, i * 2 + 2), 16);
+        }
+        return bytes;
+    }
+}

package/src/VelumXClient.ts

@@ -27,11 +27,11 @@ export class VelumXClient {
             });
 
             if (!response.ok) {
-                const errData = await response.json().catch(() => ({}));
+                const errData = await response.json().catch(() => ({ error: 'Unknown error' })) as any;
                 throw new Error(`Fee estimation failed: ${errData.error || errData.message || response.statusText}`);
             }
 
-            return await response.json();
+            return await response.json() as { maxFeeUSDCx: string, estimatedGas: number };
         } catch (error) {
             console.error("VelumX Client Error (estimateFee):", error);
             throw error;
@@ -55,11 +55,11 @@ export class VelumXClient {
             });
 
             if (!response.ok) {
-                const errData = await response.json().catch(() => ({}));
+                const errData = await response.json().catch(() => ({ error: 'Unknown error' })) as any;
                 throw new Error(`Intent sponsorship failed: ${errData.error || errData.message || response.statusText}`);
             }
 
-            return await response.json();
+            return await response.json() as { txid: string, status: string };
         } catch (error) {
             console.error("VelumX Client Error (submitIntent):", error);
             throw error;
@@ -83,11 +83,11 @@ export class VelumXClient {
             });
 
             if (!response.ok) {
-                const errData = await response.json().catch(() => ({}));
+                const errData = await response.json().catch(() => ({ error: 'Unknown error' })) as any;
                 throw new Error(`Transaction broadcast failed: ${errData.error || errData.message || response.statusText}`);
             }
 
-            return await response.json();
+            return await response.json() as { txid: string, status: string };
         } catch (error) {
             console.error("VelumX Client Error (submitRawTransaction):", error);
             throw error;

package/src/index.ts

@@ -1,8 +1,9 @@
 export * from './types';
 export * from './IntentBuilder';
 export * from './VelumXClient';
+export * from './SimplePaymaster';
 
 // Core entrypoint for the @velumx/sdk
 // Example Usage:
 // const client = new VelumXClient({ network: 'testnet' });
-// const intentBuilder = new IntentBuilder();
+// const paymaster = new SimplePaymaster({ network: 'testnet', ... });

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
     "compilerOptions": {
-        "target": "es2020",
+        "target": "es2021",
+        "lib": ["es2021", "dom"],
         "module": "commonjs",
         "declaration": true,
         "outDir": "./dist",