@varity-labs/sdk 2.0.0-alpha.1

package/dist/thirdweb/EngineClient.d.ts

@@ -0,0 +1,396 @@
+/**
+ * thirdweb Engine Client
+ *
+ * Production-grade transaction management infrastructure
+ * Replaces custom transaction queues with thirdweb's managed service
+ *
+ * Features:
+ * - Automatic transaction queueing and execution
+ * - Gas price optimization
+ * - Automatic retry with exponential backoff
+ * - Webhook notifications for transaction events
+ * - Multi-chain support
+ * - Production-ready scalability
+ */
+import type { Chain } from 'thirdweb';
+/**
+ * Engine configuration
+ */
+export interface EngineConfig {
+    /**
+     * Engine URL (e.g., https://engine.thirdweb.com or self-hosted)
+     */
+    url: string;
+    /**
+     * Access token for authentication
+     */
+    accessToken: string;
+    /**
+     * Backend wallet address to use for transactions
+     */
+    backendWalletAddress?: string;
+}
+/**
+ * Transaction parameters for Engine
+ */
+export interface EngineTransactionParams {
+    /**
+     * Chain to execute on
+     */
+    chain: Chain;
+    /**
+     * Contract address
+     */
+    to: string;
+    /**
+     * Encoded transaction data
+     */
+    data: string;
+    /**
+     * Value to send (in wei)
+     */
+    value?: string;
+    /**
+     * Gas limit
+     */
+    gasLimit?: string;
+    /**
+     * Webhook URL for transaction status updates
+     */
+    webhookUrl?: string;
+}
+/**
+ * Engine transaction status
+ */
+export type EngineTransactionStatus = 'queued' | 'sent' | 'mined' | 'errored' | 'cancelled';
+/**
+ * Engine transaction result
+ */
+export interface EngineTransactionResult {
+    /**
+     * Queue ID (unique identifier for this transaction)
+     */
+    queueId: string;
+    /**
+     * Transaction hash (available after sent)
+     */
+    transactionHash?: string;
+    /**
+     * Status
+     */
+    status: EngineTransactionStatus;
+    /**
+     * Block number (available after mined)
+     */
+    blockNumber?: number;
+    /**
+     * Error message (if errored)
+     */
+    errorMessage?: string;
+    /**
+     * Timestamp
+     */
+    timestamp: Date;
+}
+/**
+ * Contract deployment parameters for Engine
+ */
+export interface EngineDeployParams {
+    /**
+     * Chain to deploy on
+     */
+    chain: Chain;
+    /**
+     * Contract ABI
+     */
+    abi: any[];
+    /**
+     * Contract bytecode
+     */
+    bytecode: string;
+    /**
+     * Constructor arguments
+     */
+    constructorArgs?: any[];
+    /**
+     * Webhook URL for deployment status updates
+     */
+    webhookUrl?: string;
+}
+/**
+ * Engine webhook payload
+ */
+export interface EngineWebhookPayload {
+    queueId: string;
+    status: EngineTransactionStatus;
+    transactionHash?: string;
+    blockNumber?: number;
+    errorMessage?: string;
+    timestamp: string;
+}
+/**
+ * thirdweb Engine Client
+ *
+ * Manages blockchain transactions through thirdweb's production infrastructure
+ */
+export declare class EngineClient {
+    private url;
+    private accessToken;
+    private backendWalletAddress?;
+    constructor(config: EngineConfig);
+    /**
+     * Send a transaction through Engine
+     *
+     * Automatically queues, optimizes gas, and retries failed transactions.
+     *
+     * @param params - Transaction parameters
+     * @returns Transaction result with queue ID
+     *
+     * @example Basic transaction
+     * ```typescript
+     * import { EngineClient, varityL3Testnet } from '@varity-labs/sdk';
+     * import { prepareContractCall } from 'thirdweb';
+     *
+     * const engine = new EngineClient({
+     *   url: 'https://engine.varity.so',
+     *   accessToken: process.env.ENGINE_ACCESS_TOKEN,
+     *   backendWalletAddress: '0x...'
+     * });
+     *
+     * // Prepare transaction
+     * const tx = prepareContractCall({
+     *   contract,
+     *   method: 'function transfer(address to, uint256 amount)',
+     *   params: [recipientAddress, amount]
+     * });
+     *
+     * // Send through Engine
+     * const result = await engine.sendTransaction({
+     *   chain: varityL3Testnet,
+     *   to: contract.address,
+     *   data: tx.data,
+     *   value: '0'
+     * });
+     *
+     * console.log('Queue ID:', result.queueId);
+     * ```
+     *
+     * @example With webhook notifications
+     * ```typescript
+     * const result = await engine.sendTransaction({
+     *   chain: varityL3Testnet,
+     *   to: contractAddress,
+     *   data: encodedData,
+     *   webhookUrl: 'https://myapp.com/api/webhook/engine'
+     * });
+     *
+     * // Your webhook will receive status updates:
+     * // { queueId, status: 'mined', transactionHash, blockNumber }
+     * ```
+     *
+     * @example With gas limit
+     * ```typescript
+     * const result = await engine.sendTransaction({
+     *   chain: varityL3Testnet,
+     *   to: contractAddress,
+     *   data: encodedData,
+     *   gasLimit: '500000' // Override estimated gas
+     * });
+     * ```
+     */
+    sendTransaction(params: EngineTransactionParams): Promise<EngineTransactionResult>;
+    /**
+     * Deploy a contract through Engine
+     *
+     * Deploys smart contracts with automatic gas optimization and retry logic.
+     *
+     * @param params - Deployment parameters
+     * @returns Deployment result with queue ID
+     *
+     * @example Deploy ERC-721 NFT contract
+     * ```typescript
+     * import { EngineClient, varityL3Testnet } from '@varity-labs/sdk';
+     * import NFTContractABI from './abis/NFTContract.json';
+     * import NFTContractBytecode from './bytecode/NFTContract.json';
+     *
+     * const engine = new EngineClient({
+     *   url: 'https://engine.varity.so',
+     *   accessToken: process.env.ENGINE_ACCESS_TOKEN
+     * });
+     *
+     * const result = await engine.deployContract({
+     *   chain: varityL3Testnet,
+     *   abi: NFTContractABI,
+     *   bytecode: NFTContractBytecode.bytecode,
+     *   constructorArgs: [
+     *     'My NFT Collection',  // name
+     *     'MNFT',               // symbol
+     *     '0x...'               // owner address
+     *   ]
+     * });
+     *
+     * console.log('Deploying contract, Queue ID:', result.queueId);
+     * ```
+     *
+     * @example Deploy ERC-20 token
+     * ```typescript
+     * const result = await engine.deployContract({
+     *   chain: varityL3Testnet,
+     *   abi: ERC20ABI,
+     *   bytecode: ERC20Bytecode.bytecode,
+     *   constructorArgs: [
+     *     'My Token',           // name
+     *     'MTK',                // symbol
+     *     ethers.utils.parseEther('1000000')  // initial supply
+     *   ],
+     *   webhookUrl: 'https://myapp.com/api/webhook/deployment'
+     * });
+     * ```
+     *
+     * @example Deploy and wait for completion
+     * ```typescript
+     * const deployment = await engine.deployContract({
+     *   chain: varityL3Testnet,
+     *   abi: ContractABI,
+     *   bytecode: ContractBytecode.bytecode,
+     *   constructorArgs: []
+     * });
+     *
+     * // Wait for deployment to complete
+     * const completed = await engine.waitForTransaction(deployment.queueId);
+     * console.log('Contract deployed at:', completed.transactionHash);
+     * ```
+     */
+    deployContract(params: EngineDeployParams): Promise<EngineTransactionResult>;
+    /**
+     * Get transaction status
+     */
+    getTransactionStatus(queueId: string): Promise<EngineTransactionResult>;
+    /**
+     * Wait for transaction to be mined
+     *
+     * Polls Engine API until transaction is confirmed or fails.
+     *
+     * @param queueId - Engine queue ID from sendTransaction or deployContract
+     * @param options - Optional polling configuration
+     * @returns Completed transaction result
+     *
+     * @example Basic usage
+     * ```typescript
+     * import { EngineClient } from '@varity-labs/sdk';
+     *
+     * const engine = new EngineClient({ url, accessToken });
+     *
+     * // Send transaction
+     * const tx = await engine.sendTransaction({ ... });
+     *
+     * // Wait for confirmation (default: poll every 2s, timeout 5min)
+     * const result = await engine.waitForTransaction(tx.queueId);
+     * console.log('Transaction mined:', result.transactionHash);
+     * console.log('Block number:', result.blockNumber);
+     * ```
+     *
+     * @example With custom polling interval
+     * ```typescript
+     * // Poll every 5 seconds instead of default 2 seconds
+     * const result = await engine.waitForTransaction(queueId, {
+     *   pollInterval: 5000,  // 5 seconds
+     *   timeout: 600000      // 10 minutes
+     * });
+     * ```
+     *
+     * @example With error handling
+     * ```typescript
+     * try {
+     *   const result = await engine.waitForTransaction(queueId);
+     *   console.log('Success:', result.transactionHash);
+     * } catch (error) {
+     *   if (error.message.includes('timed out')) {
+     *     console.error('Transaction took too long');
+     *   } else if (error.message.includes('errored')) {
+     *     console.error('Transaction failed:', error.message);
+     *   }
+     * }
+     * ```
+     */
+    waitForTransaction(queueId: string, options?: {
+        /**
+         * Polling interval in milliseconds (default: 2000)
+         */
+        pollInterval?: number;
+        /**
+         * Maximum time to wait in milliseconds (default: 300000 = 5 minutes)
+         */
+        timeout?: number;
+    }): Promise<EngineTransactionResult>;
+    /**
+     * Cancel a queued transaction
+     */
+    cancelTransaction(queueId: string): Promise<void>;
+    /**
+     * Get backend wallet balance
+     */
+    getWalletBalance(chainId: number, walletAddress?: string): Promise<string>;
+    /**
+     * Get all backend wallets
+     */
+    getBackendWallets(): Promise<string[]>;
+    /**
+     * Get transaction nonce for a wallet
+     */
+    getNonce(chainId: number, walletAddress?: string): Promise<number>;
+    /**
+     * Make HTTP request to Engine API
+     */
+    private request;
+}
+/**
+ * Create Engine client instance
+ *
+ * Factory function for creating EngineClient instances.
+ *
+ * @param config - Engine configuration
+ * @returns Configured Engine client
+ *
+ * @example Basic setup
+ * ```typescript
+ * import { createEngineClient } from '@varity-labs/sdk';
+ *
+ * const engine = createEngineClient({
+ *   url: 'https://engine.varity.so',
+ *   accessToken: process.env.ENGINE_ACCESS_TOKEN
+ * });
+ *
+ * // Now use engine client
+ * const result = await engine.sendTransaction({ ... });
+ * ```
+ *
+ * @example With backend wallet
+ * ```typescript
+ * const engine = createEngineClient({
+ *   url: 'https://engine.varity.so',
+ *   accessToken: process.env.ENGINE_ACCESS_TOKEN,
+ *   backendWalletAddress: '0x...' // Default wallet for all transactions
+ * });
+ * ```
+ *
+ * @example Self-hosted Engine
+ * ```typescript
+ * const engine = createEngineClient({
+ *   url: 'https://my-engine.example.com',
+ *   accessToken: process.env.MY_ENGINE_TOKEN
+ * });
+ * ```
+ */
+export declare function createEngineClient(config: EngineConfig): EngineClient;
+/**
+ * Webhook handler helper
+ *
+ * Use this to handle Engine webhook notifications in your backend
+ */
+export declare function parseEngineWebhook(payload: any): EngineWebhookPayload;
+/**
+ * Verify Engine webhook signature (if configured)
+ */
+export declare function verifyEngineWebhook(payload: string, signature: string, secret: string): boolean;
+//# sourceMappingURL=EngineClient.d.ts.map

package/dist/thirdweb/EngineClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EngineClient.d.ts","sourceRoot":"","sources":["../../src/thirdweb/EngineClient.ts"],"names":[],"mappings":"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"}