@smoothsend/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 SmoothSend
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,346 @@
+# SmoothSend SDK
+
+Gasless transaction SDK for Aptos. Enable gas-free transactions with just 3 lines of code.
+
+[![npm version](https://badge.fury.io/js/@smoothsend/sdk.svg)](https://www.npmjs.com/package/@smoothsend/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 Features
+
+- **Gasless Transactions**: Users don't need APT for gas fees
+- **3-Line Integration**: Works with Aptos Wallet Adapter out of the box
+- **Type-Safe**: Full TypeScript support with comprehensive type definitions
+- **Testnet & Mainnet**: Supports both networks
+- **Fee-in-Token**: On mainnet, tiny fee deducted from token (not APT)
+
+## 📦 Installation
+
+```bash
+npm install @smoothsend/sdk
+```
+
+## ⚡ Quick Start - Wallet Adapter (EASIEST - 3 Lines!)
+
+The easiest way to integrate SmoothSend is using the Wallet Adapter integration. Just add 3 lines of code and ALL your transactions become gasless automatically!
+
+```typescript
+import { SmoothSendTransactionSubmitter } from '@smoothsend/sdk';
+import { AptosWalletAdapterProvider } from '@aptos-labs/wallet-adapter-react';
+import { Network } from '@aptos-labs/ts-sdk';
+
+// 1. Create the transaction submitter (one line!)
+const transactionSubmitter = new SmoothSendTransactionSubmitter({
+  apiKey: 'pk_nogas_your_api_key_here',
+  network: 'testnet'
+});
+
+// 2. Add to your wallet provider
+function App() {
+  return (
+    <AptosWalletAdapterProvider
+      dappConfig={{
+        network: Network.TESTNET,
+        transactionSubmitter: transactionSubmitter  // <-- That's it!
+      }}
+    >
+      <YourApp />
+    </AptosWalletAdapterProvider>
+  );
+}
+
+// 3. Use normal wallet functions - they're now gasless!
+function TransferButton() {
+  const { signAndSubmitTransaction } = useWallet();
+  
+  const handleTransfer = async () => {
+    // This is now gasless! No code changes needed!
+    const result = await signAndSubmitTransaction({
+      data: {
+        function: "0x1::coin::transfer",
+        typeArguments: ["0x1::aptos_coin::AptosCoin"],
+        functionArguments: [recipientAddress, amount],
+      }
+    });
+    console.log('Gasless transaction:', result.hash);
+  };
+  
+  return <button onClick={handleTransfer}>Send (Gasless!)</button>;
+}
+```
+
+**That's it!** All transactions in your app are now gasless. Users don't need APT for gas fees!
+
+---
+
+## 💰 Script Composer - Fee-in-Token Transfers
+
+For **mainnet with free tier**, use Script Composer to deduct fees from the token being transferred:
+
+```typescript
+import { ScriptComposerClient } from '@smoothsend/sdk';
+
+// Create client for mainnet
+const client = new ScriptComposerClient({
+  apiKey: 'pk_nogas_your_api_key',
+  network: 'mainnet'
+});
+
+// Step 1: Build transfer (fee calculated automatically)
+const { transactionBytes, fee, totalAmount } = await client.buildTransfer({
+  sender: wallet.address,
+  recipient: '0x123...',
+  amount: '1000000',     // 1 USDC
+  assetType: '0xf22bede...::usdc::USDC',
+  decimals: 6,
+  symbol: 'USDC'
+});
+
+console.log(`Sending 1 USDC, fee: ${fee} (deducted from token)`);
+
+// Step 2: Sign with wallet
+const signedTx = await wallet.signTransaction(transactionBytes);
+
+// Step 3: Submit
+const result = await client.submitSignedTransaction({
+  transactionBytes: signedTx.transactionBytes,
+  authenticatorBytes: signedTx.authenticatorBytes
+});
+
+console.log('Transaction:', result.txHash);
+```
+
+### When to Use Each Method
+
+| Scenario | Method | Why |
+|----------|--------|-----|
+| **Testnet (any tier)** | TransactionSubmitter | Always free on testnet |
+| **Mainnet + Free tier** | ScriptComposerClient | Fee deducted from token ($0.01/tx) |
+| **Mainnet + Paid tier** | TransactionSubmitter | Zero fees included in subscription |
+| **Swaps, NFTs, contracts** | TransactionSubmitter | Script Composer only supports transfers |
+| **Token transfers (monetize)** | ScriptComposerClient | Pass fee to users |
+
+### Script Composer Methods
+
+```typescript
+// Estimate fee without building transaction
+const estimate = await client.estimateFee({
+  sender: '0x...',
+  recipient: '0x...',
+  amount: '1000000',
+  assetType: USDC_ADDRESS,
+  decimals: 6,
+  symbol: 'USDC'
+});
+
+console.log('Fee:', estimate.estimation.formatted.fee);
+console.log('Total:', estimate.estimation.formatted.totalAmount);
+
+// Or use the convenience method for complete flow
+const result = await client.transfer(transferParams, wallet);
+```
+
+---
+
+## ⚠️ Important Security Update
+
+**For Aptos transactions**, the SDK uses a **secure serialized transaction approach** that requires proper wallet integration using the Aptos Wallet Standard.
+
+See the [Wallet Adapter Integration](#-quick-start---wallet-adapter-easiest---3-lines) section for the recommended implementation.
+
+## 🔑 Authentication
+
+SmoothSend uses API keys for authentication. There are two types of keys:
+
+### Public Keys (`pk_nogas_*`)
+- **Safe for frontend applications** - Can be embedded in client-side code
+- **CORS-protected** - Only work from configured domains
+- **Use in**: React apps, Vue apps, browser extensions, mobile apps
+
+### Secret Keys (`sk_nogas_*`)
+- **Server-side only** - Must never be exposed in client-side code
+- **No CORS restrictions** - Work from any server environment
+- **Use in**: Node.js backends, serverless functions, API servers
+
+### Getting Your API Keys
+
+1. Sign up at [dashboard.smoothsend.xyz](https://dashboard.smoothsend.xyz)
+2. Create a project
+3. Generate an API key pair - you'll receive both a public and secret key
+4. Configure CORS origins for your public key
+
+### Security Best Practices
+
+⚠️ **Never commit secret keys to version control**
+⚠️ **Never expose secret keys in client-side code**
+✅ **Use public keys for frontend applications**
+✅ **Use secret keys for backend services**
+✅ **Configure CORS origins for production domains**
+
+## 🏁 Classic SDK Usage
+
+If you prefer more control over the transaction flow, you can use the classic SDK approach:
+
+### Frontend Example (Public Key)
+
+```typescript
+import { SmoothSendSDK } from '@smoothsend/sdk';
+
+// Initialize with public key (safe for frontend)
+const smoothSend = new SmoothSendSDK({
+  apiKey: 'pk_nogas_your_public_key_here',
+  network: 'testnet',
+  timeout: 30000,
+  retries: 3
+});
+
+// Create a transfer request
+const transferRequest = {
+  from: '0x742d35cc6634c0532925a3b8d2d2d2d2d2d2d2d2',
+  to: '0x742d35cc6634c0532925a3b8d2d2d2d2d2d2d2d3',
+  token: 'USDC',
+  amount: '1000000', // 1 USDC (6 decimals)
+  chain: 'aptos-testnet' as const
+};
+
+// Execute transfer (with wallet signer)
+try {
+  const result = await smoothSend.transfer(transferRequest, walletSigner);
+  console.log('Transfer successful:', result.txHash);
+} catch (error) {
+  console.error('Transfer failed:', error.message);
+}
+```
+
+### Backend Example (Secret Key)
+
+```typescript
+import { SmoothSendSDK } from '@smoothsend/sdk';
+
+// Initialize with secret key (server-side only)
+const smoothSend = new SmoothSendSDK({
+  apiKey: 'sk_nogas_your_secret_key_here',
+  network: 'mainnet',
+  timeout: 30000,
+  retries: 3
+});
+
+// Execute transfer from backend
+const result = await smoothSend.executeGaslessTransfer({
+  transactionBytes: signedTx.transactionBytes,
+  authenticatorBytes: signedTx.authenticatorBytes,
+  chain: 'aptos-mainnet',
+  network: 'mainnet'
+});
+
+console.log('Transfer successful:', result.txHash);
+```
+
+## 🔧 Supported Networks
+
+| Network | Status | Features |
+|---------|--------|----------|
+| Aptos Testnet | ✅ Active | Gasless transactions, Ed25519 signatures |
+| Aptos Mainnet | ✅ Active | Gasless transactions, Fee-in-token option |
+
+## 📚 API Reference
+
+### SmoothSendTransactionSubmitter
+
+The recommended way to integrate - works with Aptos Wallet Adapter.
+
+```typescript
+import { SmoothSendTransactionSubmitter } from '@smoothsend/sdk';
+
+const submitter = new SmoothSendTransactionSubmitter({
+  apiKey: 'pk_nogas_your_api_key',
+  network: 'testnet' // or 'mainnet'
+});
+
+// Pass to AptosWalletAdapterProvider
+<AptosWalletAdapterProvider
+  dappConfig={{
+    network: Network.TESTNET,
+    transactionSubmitter: submitter
+  }}
+>
+```
+
+### ScriptComposerClient
+
+For mainnet transfers with fee-in-token (fee deducted from transferred amount).
+
+```typescript
+import { ScriptComposerClient } from '@smoothsend/sdk';
+
+const client = new ScriptComposerClient({
+  apiKey: 'pk_nogas_your_api_key',
+  network: 'mainnet'
+});
+
+// Build transfer
+const { transactionBytes, fee } = await client.buildTransfer({
+  sender: '0x...',
+  recipient: '0x...',
+  amount: '1000000',
+  assetType: USDC_ADDRESS,
+  decimals: 6,
+  symbol: 'USDC'
+});
+
+// Estimate fee
+const estimate = await client.estimateFee(transferParams);
+
+// Submit signed transaction  
+const result = await client.submitSignedTransaction({
+  transactionBytes,
+  authenticatorBytes
+});
+```
+
+### SmoothSendSDK (Classic)
+
+Direct SDK usage for more control.
+
+```typescript
+import { SmoothSendSDK } from '@smoothsend/sdk';
+
+const smoothSend = new SmoothSendSDK({
+  apiKey: 'pk_nogas_your_api_key',
+  network: 'testnet',
+  timeout: 30000,
+  retries: 3
+});
+
+// Execute gasless transfer
+const result = await smoothSend.executeGaslessTransfer({
+  transactionBytes: signedTx.transactionBytes,
+  authenticatorBytes: signedTx.authenticatorBytes,
+  chain: 'aptos-testnet',
+  network: 'testnet'
+});
+```
+
+## 🔐 Security
+
+- All transactions require user signature approval
+- Private keys never leave the client
+- Rate limiting and validation on relayer endpoints
+- Comprehensive input validation
+- Public keys are CORS-protected (safe for frontend)
+- Secret keys for backend only
+
+## 🔗 Links
+
+- **Dashboard**: [dashboard.smoothsend.xyz](https://dashboard.smoothsend.xyz)
+- **Documentation**: [docs.smoothsend.xyz](https://docs.smoothsend.xyz)
+- **GitHub**: [github.com/smoothsend](https://github.com/smoothsend)
+
+## 📄 License
+
+MIT
+
+---
+
+Built with ❤️ by the SmoothSend team
+

package/dist/adapters/aptos.d.ts

@@ -0,0 +1,98 @@
+import { SupportedChain, IChainAdapter, ChainConfig, TransferRequest, TransferQuote, SignatureData, SignedTransferData, TransferResult, TokenBalance, TokenInfo, FeeEstimate, HealthResponse } from '../types';
+/**
+ * Aptos Multi-Chain Adapter - v2 Proxy Architecture
+ * Handles all Aptos chains (aptos-testnet, aptos-mainnet)
+ * Routes all requests through proxy.smoothsend.xyz with API key authentication
+ * Supports Aptos-specific features like gasless transactions and Move-based contracts
+ */
+export declare class AptosAdapter implements IChainAdapter {
+    readonly chain: SupportedChain;
+    readonly config: ChainConfig;
+    private httpClient;
+    private apiKey;
+    private network;
+    constructor(chain: SupportedChain, config: ChainConfig, apiKey: string, network?: 'testnet' | 'mainnet', includeOrigin?: boolean);
+    /**
+     * Build API path for proxy worker routing to Aptos relayer
+     * All requests route through /api/v1/relayer/aptos/* endpoints
+     */
+    private getApiPath;
+    /**
+     * Update network parameter for subsequent requests
+     * Network is passed via X-Network header to proxy worker
+     */
+    setNetwork(network: 'testnet' | 'mainnet'): void;
+    /**
+     * Get current network
+     */
+    getNetwork(): 'testnet' | 'mainnet';
+    /**
+     * Estimate fee for a transfer (v2 interface method)
+     * Routes through proxy: POST /api/v1/relayer/aptos/quote
+     */
+    estimateFee(request: TransferRequest): Promise<FeeEstimate>;
+    /**
+     * Execute gasless transfer (v2 interface method)
+     * Routes through proxy: POST /api/v1/relayer/aptos/execute
+     */
+    executeGaslessTransfer(signedData: SignedTransferData): Promise<TransferResult>;
+    /**
+     * Get quote for a transfer (legacy method, kept for backward compatibility)
+     * Routes through proxy: POST /api/v1/relayer/aptos/quote
+     */
+    getQuote(request: TransferRequest): Promise<TransferQuote>;
+    prepareTransfer(request: TransferRequest, quote: TransferQuote): Promise<SignatureData>;
+    executeTransfer(signedData: SignedTransferData): Promise<TransferResult>;
+    getBalance(address: string, token?: string): Promise<TokenBalance[]>;
+    getTokenInfo(token: string): Promise<TokenInfo>;
+    getNonce(address: string): Promise<string>;
+    getTransactionStatus(txHash: string): Promise<any>;
+    /**
+     * Get health status of Aptos relayer through proxy
+     * Routes through proxy: GET /api/v1/relayer/aptos/health
+     */
+    getHealth(): Promise<HealthResponse>;
+    validateAddress(address: string): boolean;
+    validateAmount(amount: string): boolean;
+    /**
+     * Get Aptos token address from symbol
+     */
+    private getAptosTokenAddress;
+    /**
+     * Build Aptos explorer URL for transaction
+     */
+    private buildAptosExplorerUrl;
+    /**
+     * Validate serialized transaction data for proxy worker
+     * @param signedData The signed transfer data to validate
+     */
+    private validateSerializedTransactionData;
+    /**
+     * Enhanced address validation with detailed error messages
+     * @param address The address to validate
+     * @returns true if valid, throws error if invalid
+     */
+    validateAddressStrict(address: string): boolean;
+    /**
+     * Verify that a public key corresponds to an expected address
+     * This mirrors the enhanced verification in the relayer
+     * @param publicKey The public key to verify
+     * @param expectedAddress The expected address
+     * @returns true if they match
+     */
+    verifyPublicKeyAddress(publicKey: string, expectedAddress: string): Promise<boolean>;
+    /**
+     * Enhanced transaction preparation with better signature data structure
+     * @param request Transfer request
+     * @param quote Transfer quote
+     * @returns Signature data with enhanced structure
+     */
+    prepareTransferEnhanced(request: TransferRequest, quote: TransferQuote): Promise<SignatureData & {
+        metadata: any;
+    }>;
+    /**
+     * Aptos-specific Move contract interaction
+     */
+    callMoveFunction(functionName: string, args: any[]): Promise<any>;
+}
+//# sourceMappingURL=aptos.d.ts.map

package/dist/adapters/aptos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aptos.d.ts","sourceRoot":"","sources":["../../src/adapters/aptos.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,aAAa,EACb,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,SAAS,EACT,WAAW,EACX,cAAc,EAKf,MAAM,UAAU,CAAC;AAGlB;;;;;GAKG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,SAAgB,KAAK,EAAE,cAAc,CAAC;IACtC,SAAgB,MAAM,EAAE,WAAW,CAAC;IACpC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAwB;gBAGrC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,SAAS,GAAG,SAAqB,EAC1C,aAAa,GAAE,OAAe;IA2BhC;;;OAGG;IACH,OAAO,CAAC,UAAU;IAIlB;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IAKhD;;OAEG;IACH,UAAU,IAAI,SAAS,GAAG,SAAS;IAInC;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;IAuCjE;;;OAGG;IACG,sBAAsB,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;IAIrF;;;OAGG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAqC1D,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IA+BvF,eAAe,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;IAoDxE,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA6BpE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAiC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO1C,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAqBxD;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC;IA8B1C,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAMzC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IASvC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;;OAGG;IACH,OAAO,CAAC,iCAAiC;IA0CzC;;;;OAIG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAuB/C;;;;;;OAMG;IACG,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkB1F;;;;;OAKG;IACG,uBAAuB,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,GAAG;QAAE,QAAQ,EAAE,GAAG,CAAA;KAAE,CAAC;IAmBzH;;OAEG;IACG,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC;CAuBxE"}