@velumx/sdk 1.0.0

package/dist/IntentBuilder.d.ts

@@ -0,0 +1,22 @@
+import { WalletIntent, SignedIntent } from './types';
+export declare class IntentBuilder {
+    private domainName;
+    private domainVersion;
+    private chainId;
+    constructor(network?: 'mainnet' | 'testnet' | 'devnet');
+    /**
+     * Builds the SIP-018 structured data domain
+     */
+    private getDomain;
+    /**
+     * Formats the intent into a Clarity Tuple for signing
+     * Structure matches the Smart Wallet expectation
+     */
+    private formatIntentMessage;
+    /**
+     * Signs an intent using a private key
+     * In a browser environment, this would use a wallet popup (e.g. Leather/Xverse)
+     * For Node.js/Backend, it signs directly.
+     */
+    signIntent(intent: WalletIntent, privateKey: string): SignedIntent;
+}

package/dist/IntentBuilder.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntentBuilder = void 0;
+const transactions_1 = require("@stacks/transactions");
+class IntentBuilder {
+    constructor(network = 'mainnet') {
+        this.domainName = "SGAL-Smart-Wallet";
+        this.domainVersion = "1.0.0";
+        this.chainId = network === 'mainnet' ? 1 : 2147483648; // Testnet chain ID
+    }
+    /**
+     * Builds the SIP-018 structured data domain
+     */
+    getDomain() {
+        return (0, transactions_1.tupleCV)({
+            name: (0, transactions_1.stringAsciiCV)(this.domainName),
+            version: (0, transactions_1.stringAsciiCV)(this.domainVersion),
+            'chain-id': (0, transactions_1.uintCV)(this.chainId)
+        });
+    }
+    /**
+     * Formats the intent into a Clarity Tuple for signing
+     * Structure matches the Smart Wallet expectation
+     */
+    formatIntentMessage(intent) {
+        return (0, transactions_1.tupleCV)({
+            target: (0, transactions_1.principalCV)(intent.target),
+            'function-name': (0, transactions_1.stringAsciiCV)(intent.functionName),
+            args: (0, transactions_1.listCV)(intent.args),
+            'max-fee-usdcx': (0, transactions_1.uintCV)(intent.maxFeeUSDCx),
+            nonce: (0, transactions_1.uintCV)(intent.nonce),
+            deadline: intent.deadline ? (0, transactions_1.someCV)((0, transactions_1.uintCV)(intent.deadline)) : (0, transactions_1.noneCV)()
+        });
+    }
+    /**
+     * Signs an intent using a private key
+     * In a browser environment, this would use a wallet popup (e.g. Leather/Xverse)
+     * For Node.js/Backend, it signs directly.
+     */
+    signIntent(intent, privateKey) {
+        const domain = this.getDomain();
+        const message = this.formatIntentMessage(intent);
+        // Uses Stacks.js SIP-018 signing utility
+        // Note: For dApps, use the '@stacks/connect' openSignatureRequest instead
+        const signature = (0, transactions_1.signStructuredData)({
+            message,
+            domain,
+            privateKey
+        });
+        return {
+            ...intent,
+            signature
+        };
+    }
+}
+exports.IntentBuilder = IntentBuilder;

package/dist/VelumXClient.d.ts

@@ -0,0 +1,20 @@
+import { SignedIntent, NetworkConfig } 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
+     */
+    estimateFee(intent: any): Promise<{
+        maxFeeUSDCx: string;
+        estimatedGas: number;
+    }>;
+    /**
+     * Submit a signed intent to the relayer for sponsorship and execution
+     */
+    submitIntent(signedIntent: SignedIntent): Promise<{
+        txid: string;
+        status: string;
+    }>;
+}

package/dist/VelumXClient.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VelumXClient = void 0;
+class VelumXClient {
+    constructor(config) {
+        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
+     */
+    async estimateFee(intent) {
+        try {
+            const headers = { 'Content-Type': 'application/json' };
+            if (this.config.apiKey) {
+                headers['x-api-key'] = this.config.apiKey;
+            }
+            const response = await fetch(`${this.relayerUrl}/estimate`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ intent })
+            });
+            if (!response.ok) {
+                throw new Error(`Fee estimation failed: ${response.statusText}`);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            console.error("VelumX Client Error (estimateFee):", error);
+            throw error;
+        }
+    }
+    /**
+     * Submit a signed intent to the relayer for sponsorship and execution
+     */
+    async submitIntent(signedIntent) {
+        try {
+            const headers = { 'Content-Type': 'application/json' };
+            if (this.config.apiKey) {
+                headers['x-api-key'] = this.config.apiKey;
+            }
+            const response = await fetch(`${this.relayerUrl}/sponsor`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ intent: signedIntent })
+            });
+            if (!response.ok) {
+                const errData = await response.json().catch(() => ({}));
+                throw new Error(`Intent sponsorship failed: ${errData.message || response.statusText}`);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            console.error("VelumX Client Error (submitIntent):", error);
+            throw error;
+        }
+    }
+}
+exports.VelumXClient = VelumXClient;

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./IntentBuilder"), exports);
+__exportStar(require("./VelumXClient"), exports);
+// Core entrypoint for the @velumx/sdk
+// Example Usage:
+// const client = new VelumXClient({ network: 'testnet' });
+// const intentBuilder = new IntentBuilder();

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+import { ClarityValue } from '@stacks/transactions';
+export interface WalletIntent {
+    target: string;
+    functionName: string;
+    args: ClarityValue[];
+    maxFeeUSDCx: string | number;
+    nonce: string | number;
+    deadline?: string | number;
+}
+export interface SignedIntent extends WalletIntent {
+    signature: string;
+}
+export interface NetworkConfig {
+    coreApiUrl: string;
+    network: 'mainnet' | 'testnet' | 'devnet';
+    paymasterUrl?: string;
+    apiKey?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@velumx/sdk",
+  "version": "1.0.0",
+  "description": "VelumX Gas Abstraction Layer SDK for dApps",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "clean": "if exist dist rmdir /s /q dist",
+    "build": "npm run clean && tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "stacks",
+    "stx",
+    "gasless",
+    "paymaster",
+    "account-abstraction"
+  ],
+  "author": "VelumX",
+  "license": "MIT",
+  "dependencies": {
+    "@stacks/common": "^7.3.1",
+    "@stacks/network": "^7.3.1",
+    "@stacks/transactions": "^7.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/IntentBuilder.ts

@@ -0,0 +1,70 @@
+import {
+    signStructuredData,
+    tupleCV,
+    uintCV,
+    principalCV,
+    stringAsciiCV,
+    noneCV,
+    someCV,
+    listCV
+} from '@stacks/transactions';
+import { WalletIntent, SignedIntent } from './types';
+
+export class IntentBuilder {
+    private domainName = "SGAL-Smart-Wallet";
+    private domainVersion = "1.0.0";
+    private chainId: number;
+
+    constructor(network: 'mainnet' | 'testnet' | 'devnet' = 'mainnet') {
+        this.chainId = network === 'mainnet' ? 1 : 2147483648; // Testnet chain ID
+    }
+
+    /**
+     * Builds the SIP-018 structured data domain
+     */
+    private getDomain() {
+        return tupleCV({
+            name: stringAsciiCV(this.domainName),
+            version: stringAsciiCV(this.domainVersion),
+            'chain-id': uintCV(this.chainId)
+        });
+    }
+
+    /**
+     * Formats the intent into a Clarity Tuple for signing
+     * Structure matches the Smart Wallet expectation
+     */
+    private formatIntentMessage(intent: WalletIntent) {
+        return tupleCV({
+            target: principalCV(intent.target),
+            'function-name': stringAsciiCV(intent.functionName),
+            args: listCV(intent.args),
+            'max-fee-usdcx': uintCV(intent.maxFeeUSDCx),
+            nonce: uintCV(intent.nonce),
+            deadline: intent.deadline ? someCV(uintCV(intent.deadline)) : noneCV()
+        });
+    }
+
+    /**
+     * Signs an intent using a private key
+     * In a browser environment, this would use a wallet popup (e.g. Leather/Xverse)
+     * For Node.js/Backend, it signs directly.
+     */
+    public signIntent(intent: WalletIntent, privateKey: string): SignedIntent {
+        const domain = this.getDomain();
+        const message = this.formatIntentMessage(intent);
+
+        // Uses Stacks.js SIP-018 signing utility
+        // Note: For dApps, use the '@stacks/connect' openSignatureRequest instead
+        const signature = signStructuredData({
+            message,
+            domain,
+            privateKey
+        });
+
+        return {
+            ...intent,
+            signature
+        };
+    }
+}

package/src/VelumXClient.ts

@@ -0,0 +1,67 @@
+import { SignedIntent, NetworkConfig } from './types';
+
+export class VelumXClient {
+    private config: NetworkConfig;
+    private relayerUrl: string;
+
+    constructor(config: NetworkConfig) {
+        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
+     */
+    public async estimateFee(intent: any): Promise<{ maxFeeUSDCx: string, estimatedGas: number }> {
+        try {
+            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+            if (this.config.apiKey) {
+                headers['x-api-key'] = this.config.apiKey;
+            }
+
+            const response = await fetch(`${this.relayerUrl}/estimate`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ intent })
+            });
+
+            if (!response.ok) {
+                throw new Error(`Fee estimation failed: ${response.statusText}`);
+            }
+
+            return await response.json();
+        } catch (error) {
+            console.error("VelumX Client Error (estimateFee):", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Submit a signed intent to the relayer for sponsorship and execution
+     */
+    public async submitIntent(signedIntent: SignedIntent): Promise<{ txid: string, status: string }> {
+        try {
+            const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+            if (this.config.apiKey) {
+                headers['x-api-key'] = this.config.apiKey;
+            }
+
+            const response = await fetch(`${this.relayerUrl}/sponsor`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ intent: signedIntent })
+            });
+
+            if (!response.ok) {
+                const errData = await response.json().catch(() => ({}));
+                throw new Error(`Intent sponsorship failed: ${errData.message || response.statusText}`);
+            }
+
+            return await response.json();
+        } catch (error) {
+            console.error("VelumX Client Error (submitIntent):", error);
+            throw error;
+        }
+    }
+}

package/src/index.ts

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

package/src/types.ts

@@ -0,0 +1,21 @@
+import { principalCV, uintCV, stringAsciiCV, tupleCV, someCV, noneCV, ClarityValue } from '@stacks/transactions';
+
+export interface WalletIntent {
+    target: string;
+    functionName: string;
+    args: ClarityValue[];
+    maxFeeUSDCx: string | number; // uint represented as string or number
+    nonce: string | number;
+    deadline?: string | number; // Future feature
+}
+
+export interface SignedIntent extends WalletIntent {
+    signature: string;
+}
+
+export interface NetworkConfig {
+    coreApiUrl: string;
+    network: 'mainnet' | 'testnet' | 'devnet';
+    paymasterUrl?: string; // URL for the SGAL relayer service
+    apiKey?: string; // SGAL API Key
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "compilerOptions": {
+        "target": "es2020",
+        "module": "commonjs",
+        "declaration": true,
+        "outDir": "./dist",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": [
+        "src/**/*"
+    ]
+}