pepay-streams-sdk 0.1.0

package/src/automation/index.ts

@@ -0,0 +1,436 @@
+/**
+ * Automation Module
+ *
+ * Provides methods for keeper automation:
+ * - Enable/disable auto-withdraw for vesting campaigns
+ * - Enable/disable auto-release for locks
+ * - Query automation status
+ */
+import {
+  type PublicClient,
+  type WalletClient,
+  type Address,
+  type Hash,
+} from 'viem';
+import { DIAMOND_ABI } from '@pepay-streams/abi/diamond';
+import type {
+  EnableAutoWithdrawParams,
+  EnableAutoReleaseParams,
+  AutomationStatus,
+  TransactionResult,
+} from '../types';
+
+/**
+ * Automation module for keeper-powered operations
+ */
+export class AutomationModule {
+  constructor(
+    private readonly publicClient: PublicClient,
+    private readonly walletClient: WalletClient | undefined,
+    private readonly diamondAddress: Address
+  ) {}
+
+  // ============================================================================
+  // Auto-Withdraw (for Vesting campaigns)
+  // ============================================================================
+
+  /**
+   * Enable auto-withdraw for a vesting campaign
+   *
+   * Keepers will automatically claim vested tokens on behalf of recipients.
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.automation.enableAutoWithdraw({
+   *   campaignId: 1n,
+   *   frequency: 7 * 24 * 60 * 60, // Weekly
+   *   tipAmount: parseEther('0.1'), // 0.1 ETH for keeper
+   * });
+   * ```
+   */
+  async enableAutoWithdraw(
+    params: EnableAutoWithdrawParams
+  ): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'enableAutoWithdraw',
+      args: [params.campaignId, BigInt(params.frequency)],
+      value: params.tipAmount ?? 0n,
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  /**
+   * Disable auto-withdraw for a campaign
+   *
+   * Returns remaining tip balance to caller.
+   */
+  async disableAutoWithdraw(campaignId: bigint): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'disableAutoWithdraw',
+      args: [campaignId],
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  // ============================================================================
+  // Auto-Release (for Lock campaigns)
+  // ============================================================================
+
+  /**
+   * Enable auto-release for a lock campaign
+   *
+   * Keepers will automatically release tokens when unlock time passes.
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.automation.enableAutoRelease({
+   *   campaignId: 5n,
+   *   frequency: 3600, // Check every hour
+   *   tipAmount: parseEther('0.05'), // 0.05 ETH for keeper
+   * });
+   * ```
+   */
+  async enableAutoRelease(
+    params: EnableAutoReleaseParams & { frequency?: number }
+  ): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    // Default frequency of 1 hour if not specified
+    const frequency = params.frequency ?? 3600;
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'enableAutoReleaseLock',
+      args: [params.campaignId, BigInt(frequency)],
+      value: params.tipAmount ?? 0n,
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  /**
+   * Disable auto-release for a lock campaign
+   */
+  async disableAutoRelease(campaignId: bigint): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'disableAutoReleaseLock',
+      args: [campaignId],
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  // ============================================================================
+  // Automation Status Queries
+  // ============================================================================
+
+  /**
+   * Get auto-withdraw status for a campaign
+   *
+   * @example
+   * ```typescript
+   * const status = await sdk.automation.getAutoWithdrawStatus(campaignId);
+   * console.log('Enabled:', status.enabled);
+   * console.log('Next run:', new Date(status.nextRun * 1000));
+   * console.log('Tip balance:', formatEther(status.tipBalance));
+   * ```
+   */
+  async getAutoWithdrawStatus(campaignId: bigint): Promise<AutomationStatus> {
+    const [config, pendingCount, cursor] = await Promise.all([
+      this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DIAMOND_ABI,
+        functionName: 'automationConfig',
+        args: [campaignId],
+      }) as Promise<[boolean, bigint, bigint]>,
+      this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DIAMOND_ABI,
+        functionName: 'recipientsPending',
+        args: [campaignId],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DIAMOND_ABI,
+        functionName: 'regCursor',
+        args: [campaignId],
+      }) as Promise<bigint>,
+    ]);
+
+    const [enabled, frequency, lastRun] = config;
+    const nextRun = Number(lastRun) + Number(frequency);
+
+    return {
+      enabled,
+      lastRun: Number(lastRun),
+      nextRun,
+      frequency: Number(frequency),
+      tipBalance: 0n, // Tip balance is managed internally
+      recipientsProcessed: Number(cursor),
+      totalRecipients: Number(pendingCount) + Number(cursor),
+    };
+  }
+
+  /**
+   * Get auto-release status for a lock campaign
+   */
+  async getAutoReleaseStatus(campaignId: bigint): Promise<{
+    enabled: boolean;
+    frequency: number;
+    lastRun: number;
+    nextRun: number;
+  }> {
+    const config = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'automationLockConfig',
+      args: [campaignId],
+    }) as [boolean, bigint, bigint];
+
+    const [enabled, frequency, lastRun] = config;
+    const nextRun = Number(lastRun) + Number(frequency);
+
+    return {
+      enabled,
+      frequency: Number(frequency),
+      lastRun: Number(lastRun),
+      nextRun,
+    };
+  }
+
+  /**
+   * Preview automation for specific recipients
+   */
+  async previewAutomation(
+    campaignId: bigint,
+    recipients: Address[]
+  ): Promise<{
+    pendingCount: bigint;
+    nextFeeWei: bigint;
+    escrowWei: bigint;
+  }> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'automationPreviewFor',
+      args: [campaignId, recipients],
+    }) as [bigint, bigint, bigint];
+
+    return {
+      pendingCount: result[0],
+      nextFeeWei: result[1],
+      escrowWei: result[2],
+    };
+  }
+
+  /**
+   * Get automation run statistics
+   */
+  async getAutomationStats(
+    campaignId: bigint,
+    lockMode = false
+  ): Promise<{
+    runsObserved: number;
+    avgRecipientsPerRun: number;
+    lastRecipientsProcessed: number;
+    maxRecipientsPerRun: number;
+  }> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'automationRunStats',
+      args: [campaignId, lockMode],
+    }) as {
+      runsObserved: bigint;
+      avgRecipientsPerRun: bigint;
+      lastRecipientsProcessed: bigint;
+      maxRecipientsPerRun: bigint;
+    };
+
+    return {
+      runsObserved: Number(result.runsObserved),
+      avgRecipientsPerRun: Number(result.avgRecipientsPerRun),
+      lastRecipientsProcessed: Number(result.lastRecipientsProcessed),
+      maxRecipientsPerRun: Number(result.maxRecipientsPerRun),
+    };
+  }
+
+  /**
+   * Check if auto-withdraw is currently runnable
+   *
+   * Returns true if cooldown has passed and there are pending recipients.
+   */
+  async isAutoWithdrawRunnable(campaignId: bigint): Promise<boolean> {
+    const status = await this.getAutoWithdrawStatus(campaignId);
+    const now = Math.floor(Date.now() / 1000);
+
+    return (
+      status.enabled &&
+      now >= status.nextRun &&
+      status.recipientsProcessed < status.totalRecipients
+    );
+  }
+
+  /**
+   * Check if auto-release is currently runnable
+   */
+  async isAutoReleaseRunnable(campaignId: bigint): Promise<boolean> {
+    const status = await this.getAutoReleaseStatus(campaignId);
+    const now = Math.floor(Date.now() / 1000);
+
+    return status.enabled && now >= status.nextRun;
+  }
+
+  // ============================================================================
+  // Keeper Functions (for automation operators)
+  // ============================================================================
+
+  /**
+   * Execute auto-withdraw for specific recipients (keeper only)
+   *
+   * @example
+   * ```typescript
+   * // Get recipients from registry or external source
+   * const recipients = ['0x...', '0x...', '0x...'];
+   * await sdk.automation.executeAutoWithdraw(campaignId, recipients);
+   * ```
+   */
+  async executeAutoWithdraw(
+    campaignId: bigint,
+    recipients: Address[]
+  ): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'autoWithdraw',
+      args: [campaignId, recipients],
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  /**
+   * Execute auto-withdraw using registry cursor (keeper only)
+   *
+   * Processes up to batchSize recipients from the registry.
+   */
+  async executeAutoWithdrawNext(
+    campaignId: bigint,
+    batchSize = 50
+  ): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'autoWithdrawNext',
+      args: [campaignId, BigInt(batchSize)],
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  /**
+   * Execute auto-release for specific recipients (keeper only)
+   */
+  async executeAutoRelease(
+    campaignId: bigint,
+    recipients: Address[]
+  ): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'autoReleaseLock',
+      args: [campaignId, recipients],
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  /**
+   * Execute auto-release using registry cursor (keeper only)
+   */
+  async executeAutoReleaseNext(
+    campaignId: bigint,
+    batchSize = 50
+  ): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'autoReleaseLockNext',
+      args: [campaignId, BigInt(batchSize)],
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  // ============================================================================
+  // Helpers
+  // ============================================================================
+
+  private requireWallet(): WalletClient {
+    if (!this.walletClient) {
+      throw new Error(
+        'Wallet client required for write operations. Initialize SDK with a signer.'
+      );
+    }
+    return this.walletClient;
+  }
+
+  private createTransactionResult(hash: Hash): TransactionResult {
+    return {
+      hash,
+      wait: async () => {
+        const receipt = await this.publicClient.waitForTransactionReceipt({
+          hash,
+        });
+        return {
+          blockNumber: receipt.blockNumber,
+          transactionHash: receipt.transactionHash,
+          gasUsed: receipt.gasUsed,
+          status: receipt.status,
+          logs: receipt.logs,
+        };
+      },
+    };
+  }
+}
+
+export default AutomationModule;