@agirails/sdk 2.0.1-beta → 2.0.2

package/src/cli/commands/simulate.ts

@@ -0,0 +1,345 @@
+/**
+ * Simulate Command - Dry-run commands without executing
+ *
+ * Agent-first feature: Preview what a command would do
+ * without actually executing it. Perfect for:
+ * - Testing scripts before running on mainnet
+ * - Understanding fee calculations
+ * - Validating input parameters
+ *
+ * @module cli/commands/simulate
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode, fmt } from '../utils/output';
+import { loadConfig } from '../utils/config';
+import { mapError } from '../utils/client';
+import { BaseAdapter, ValidationError, MIN_AMOUNT_WEI } from '../../adapters/BaseAdapter';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createSimulateCommand(): Command {
+  const cmd = new Command('simulate')
+    .description('Dry-run a command without executing (agent-first feature)');
+
+  cmd.addCommand(createSimulatePayCommand());
+  cmd.addCommand(createSimulateFeeCommand());
+
+  return cmd;
+}
+
+// ============================================================================
+// simulate pay
+// ============================================================================
+
+function createSimulatePayCommand(): Command {
+  return new Command('pay')
+    .description('Simulate a payment transaction')
+    .argument('<to>', 'Provider address')
+    .argument('<amount>', 'Amount to pay')
+    .option('-d, --deadline <deadline>', 'Deadline (+24h, +7d, or Unix timestamp)', '+24h')
+    .option('--json', 'Output as JSON')
+    .action(async (to, amount, options) => {
+      const output = new Output(options.json ? 'json' : 'human');
+
+      try {
+        await runSimulatePay(to, amount, options, output);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+interface SimulatePayOptions {
+  deadline: string;
+  json?: boolean;
+}
+
+async function runSimulatePay(
+  to: string,
+  amount: string,
+  options: SimulatePayOptions,
+  output: Output
+): Promise<void> {
+  const config = loadConfig();
+
+  // Create a mock adapter just for parsing
+  const adapter = new SimulationAdapter(config.address);
+
+  // Validate and parse inputs
+  const validation = adapter.validatePayment(to, amount, options.deadline);
+
+  if (!validation.valid) {
+    output.result({
+      valid: false,
+      errors: validation.errors,
+    });
+    process.exit(ExitCode.INVALID_INPUT);
+  }
+
+  // Calculate fee
+  const amountWei = validation.parsedAmount!;
+  const feeCalculation = calculateFee(amountWei);
+
+  const result = {
+    valid: true,
+    simulation: {
+      action: 'CREATE_AND_FUND_TRANSACTION',
+      provider: to.toLowerCase(),
+      requester: config.address.toLowerCase(),
+      amount: formatUsdc(amountWei.toString()) + ' USDC',
+      amountWei: amountWei.toString(),
+      deadline: new Date(validation.parsedDeadline! * 1000).toISOString(),
+      deadlineUnix: validation.parsedDeadline,
+    },
+    fees: {
+      platformFee: formatUsdc(feeCalculation.fee.toString()) + ' USDC',
+      platformFeeWei: feeCalculation.fee.toString(),
+      feeRate: feeCalculation.effectiveRate,
+      providerReceives: formatUsdc(feeCalculation.providerReceives.toString()) + ' USDC',
+      minimumApplied: feeCalculation.minimumApplied,
+    },
+    requirements: {
+      requiredBalance: formatUsdc((amountWei + feeCalculation.fee).toString()) + ' USDC',
+      mode: config.mode,
+    },
+    warnings: validation.warnings,
+  };
+
+  if (options.json) {
+    output.result(result);
+  } else {
+    output.section('Simulation Results');
+    output.print('');
+    output.print(fmt.bold('Transaction Details:'));
+    output.keyValue('  Action', 'Create and fund transaction');
+    output.keyValue('  Provider', to);
+    output.keyValue('  Amount', result.simulation.amount);
+    output.keyValue('  Deadline', result.simulation.deadline);
+    output.print('');
+    output.print(fmt.bold('Fee Breakdown (1% + $0.05 min):'));
+    output.keyValue('  Platform Fee', result.fees.platformFee);
+    output.keyValue('  Effective Rate', result.fees.feeRate);
+    output.keyValue('  Provider Receives', result.fees.providerReceives);
+    if (feeCalculation.minimumApplied) {
+      output.print(fmt.yellow('  (Minimum fee applied - amount < $5)'));
+    }
+    output.print('');
+    output.print(fmt.bold('Requirements:'));
+    output.keyValue('  Required Balance', result.requirements.requiredBalance);
+    output.keyValue('  Mode', result.requirements.mode);
+
+    if (validation.warnings && validation.warnings.length > 0) {
+      output.print('');
+      output.print(fmt.yellow('Warnings:'));
+      for (const warning of validation.warnings) {
+        output.print(fmt.yellow(`  - ${warning}`));
+      }
+    }
+
+    output.print('');
+    output.success('Simulation complete - no transaction created');
+  }
+}
+
+// ============================================================================
+// simulate fee
+// ============================================================================
+
+function createSimulateFeeCommand(): Command {
+  return new Command('fee')
+    .description('Calculate fee for a given amount')
+    .argument('<amount>', 'Amount to calculate fee for')
+    .option('--json', 'Output as JSON')
+    .action(async (amount, options) => {
+      const output = new Output(options.json ? 'json' : 'human');
+
+      try {
+        // Parse amount
+        const adapter = new SimulationAdapter('0x0000000000000000000000000000000000000000');
+        const parsedAmount = adapter.parseAmountPublic(amount);
+
+        const feeCalc = calculateFee(parsedAmount);
+
+        const result = {
+          amount: formatUsdc(parsedAmount.toString()) + ' USDC',
+          amountWei: parsedAmount.toString(),
+          fee: formatUsdc(feeCalc.fee.toString()) + ' USDC',
+          feeWei: feeCalc.fee.toString(),
+          effectiveRate: feeCalc.effectiveRate,
+          providerReceives: formatUsdc(feeCalc.providerReceives.toString()) + ' USDC',
+          totalRequired: formatUsdc((parsedAmount + feeCalc.fee).toString()) + ' USDC',
+          minimumApplied: feeCalc.minimumApplied,
+        };
+
+        if (options.json) {
+          output.result(result);
+        } else {
+          output.section('Fee Calculation');
+          output.keyValue('Amount', result.amount);
+          output.keyValue('Platform Fee', result.fee);
+          output.keyValue('Effective Rate', result.effectiveRate);
+          output.keyValue('Provider Receives', result.providerReceives);
+          output.keyValue('Total Required', result.totalRequired);
+          if (feeCalc.minimumApplied) {
+            output.print('');
+            output.info('Minimum fee ($0.05) applied because amount < $5');
+          }
+        }
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Extended adapter for simulation purposes
+ */
+class SimulationAdapter extends BaseAdapter {
+  constructor(requesterAddress: string) {
+    super(requesterAddress);
+  }
+
+  /**
+   * Validate payment parameters without executing
+   */
+  validatePayment(
+    to: string,
+    amount: string | number,
+    deadline?: string | number
+  ): {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    parsedAmount?: bigint;
+    parsedDeadline?: number;
+  } {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+    let parsedAmount: bigint | undefined;
+    let parsedDeadline: number | undefined;
+
+    // Validate address
+    try {
+      this.validateAddress(to, 'to');
+    } catch (e) {
+      errors.push((e as Error).message);
+    }
+
+    // Validate amount
+    try {
+      parsedAmount = this.parseAmount(amount);
+
+      // Check for small amount warning
+      if (parsedAmount < 5_000_000n) {
+        // Less than $5
+        warnings.push('Amount is below $5 - minimum fee ($0.05) will apply');
+      }
+    } catch (e) {
+      errors.push((e as Error).message);
+    }
+
+    // Validate deadline
+    try {
+      const currentTime = Math.floor(Date.now() / 1000);
+      parsedDeadline = this.parseDeadline(deadline, currentTime);
+
+      if (parsedDeadline <= currentTime) {
+        errors.push('Deadline must be in the future');
+      }
+
+      // Check for short deadline warning
+      const hoursUntilDeadline = (parsedDeadline - currentTime) / 3600;
+      if (hoursUntilDeadline < 1) {
+        warnings.push('Deadline is less than 1 hour from now');
+      }
+    } catch (e) {
+      errors.push((e as Error).message);
+    }
+
+    // Check self-payment
+    if (to.toLowerCase() === this.requesterAddress.toLowerCase()) {
+      errors.push('Cannot pay yourself');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      parsedAmount,
+      parsedDeadline,
+    };
+  }
+
+  /**
+   * Public access to parseAmount for fee calculation
+   */
+  parseAmountPublic(amount: string | number): bigint {
+    return this.parseAmount(amount);
+  }
+}
+
+/**
+ * Calculate platform fee based on AGIRAILS fee model:
+ * - 1% of transaction amount
+ * - $0.05 minimum
+ */
+function calculateFee(amountWei: bigint): {
+  fee: bigint;
+  providerReceives: bigint;
+  effectiveRate: string;
+  minimumApplied: boolean;
+} {
+  // 1% fee
+  const percentFee = amountWei / 100n;
+
+  // $0.05 minimum in wei (6 decimals)
+  const minimumFeeWei = 50_000n;
+
+  // Apply minimum
+  const fee = percentFee > minimumFeeWei ? percentFee : minimumFeeWei;
+  const minimumApplied = percentFee < minimumFeeWei;
+
+  // Calculate what provider receives (amount minus fee)
+  const providerReceives = amountWei - fee;
+
+  // Calculate effective rate
+  const effectiveRatePercent = (Number(fee) / Number(amountWei)) * 100;
+  const effectiveRate = effectiveRatePercent.toFixed(2) + '%';
+
+  return {
+    fee,
+    providerReceives,
+    effectiveRate,
+    minimumApplied,
+  };
+}
+
+/**
+ * Format USDC amount from wei to decimal
+ */
+function formatUsdc(weiAmount: string): string {
+  const amount = BigInt(weiAmount);
+  const whole = amount / 1_000_000n;
+  const decimal = amount % 1_000_000n;
+  const decimalStr = decimal.toString().padStart(6, '0').slice(0, 2);
+  return `${whole}.${decimalStr}`;
+}
+
+export { runSimulatePay, calculateFee };

package/src/cli/commands/time.ts

@@ -0,0 +1,303 @@
+/**
+ * Time Command - Manipulate mock blockchain time
+ *
+ * Mock mode only feature for testing time-dependent logic:
+ * - Deadline expiration
+ * - Dispute window progression
+ * - Time-based state transitions
+ *
+ * @module cli/commands/time
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode, fmt } from '../utils/output';
+import { loadConfig } from '../utils/config';
+import { createClient, mapError } from '../utils/client';
+import { MockRuntime } from '../../runtime/MockRuntime';
+import { IMockRuntime } from '../../runtime/IACTPRuntime';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createTimeCommand(): Command {
+  const cmd = new Command('time')
+    .description('Manipulate mock blockchain time (mock mode only)');
+
+  cmd.addCommand(createTimeShowCommand());
+  cmd.addCommand(createTimeAdvanceCommand());
+  cmd.addCommand(createTimeSetCommand());
+
+  return cmd;
+}
+
+// ============================================================================
+// time show
+// ============================================================================
+
+function createTimeShowCommand(): Command {
+  return new Command('show')
+    .description('Show current mock blockchain time')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only the timestamp')
+    .action(async (options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        validateMockMode();
+
+        const client = await createClient();
+        const runtime = client.runtime as IMockRuntime;
+        const currentTime = runtime.time.now();
+
+        if (options.quiet) {
+          console.log(currentTime);
+          return;
+        }
+
+        output.result({
+          timestamp: currentTime,
+          iso: new Date(currentTime * 1000).toISOString(),
+          readable: formatRelativeTime(currentTime),
+        });
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// time advance
+// ============================================================================
+
+function createTimeAdvanceCommand(): Command {
+  return new Command('advance')
+    .description('Advance mock blockchain time')
+    .argument('<duration>', 'Duration to advance (e.g., "1h", "30m", "7d", "3600")')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Minimal output')
+    .action(async (duration, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        validateMockMode();
+
+        const seconds = parseDuration(duration);
+        if (seconds <= 0) {
+          throw new Error('Duration must be positive');
+        }
+
+        const client = await createClient();
+        const runtime = client.runtime as IMockRuntime;
+
+        const beforeTime = runtime.time.now();
+        await runtime.time.advanceTime(seconds);
+        const afterTime = runtime.time.now();
+
+        output.result({
+          advanced: seconds,
+          advancedReadable: formatDuration(seconds),
+          beforeTimestamp: beforeTime,
+          afterTimestamp: afterTime,
+          afterIso: new Date(afterTime * 1000).toISOString(),
+        });
+
+        output.success(`Advanced time by ${formatDuration(seconds)}`);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// time set
+// ============================================================================
+
+function createTimeSetCommand(): Command {
+  return new Command('set')
+    .description('Set mock blockchain time to specific timestamp')
+    .argument('<timestamp>', 'Unix timestamp or ISO date')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Minimal output')
+    .action(async (timestamp, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        validateMockMode();
+
+        const targetTime = parseTimestamp(timestamp);
+
+        const client = await createClient();
+        const runtime = client.runtime as IMockRuntime;
+
+        const beforeTime = runtime.time.now();
+
+        if (targetTime < beforeTime) {
+          throw new Error(
+            'Cannot set time in the past.\n' +
+              `Current time: ${beforeTime}\n` +
+              `Target time: ${targetTime}`
+          );
+        }
+
+        await runtime.time.setTime(targetTime);
+
+        output.result({
+          beforeTimestamp: beforeTime,
+          afterTimestamp: targetTime,
+          afterIso: new Date(targetTime * 1000).toISOString(),
+        });
+
+        output.success(`Set time to ${new Date(targetTime * 1000).toISOString()}`);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Validate that we're in mock mode
+ */
+function validateMockMode(): void {
+  const config = loadConfig();
+  if (config.mode !== 'mock') {
+    throw new Error(
+      'Time commands only available in mock mode.\n' +
+        `Current mode: ${config.mode}`
+    );
+  }
+}
+
+/**
+ * Parse duration string to seconds
+ *
+ * Supports:
+ * - "30s" - 30 seconds
+ * - "5m" - 5 minutes
+ * - "2h" - 2 hours
+ * - "7d" - 7 days
+ * - "3600" - raw seconds
+ */
+function parseDuration(duration: string): number {
+  // Raw number (seconds)
+  if (/^\d+$/.test(duration)) {
+    return parseInt(duration, 10);
+  }
+
+  // Duration with unit
+  const match = duration.match(/^(\d+(?:\.\d+)?)(s|m|h|d)$/);
+  if (!match) {
+    throw new Error(
+      `Invalid duration format: "${duration}"\n` +
+        'Expected format: "30s", "5m", "2h", "7d", or raw seconds'
+    );
+  }
+
+  const [, valueStr, unit] = match;
+  const value = parseFloat(valueStr);
+
+  switch (unit) {
+    case 's':
+      return Math.floor(value);
+    case 'm':
+      return Math.floor(value * 60);
+    case 'h':
+      return Math.floor(value * 3600);
+    case 'd':
+      return Math.floor(value * 86400);
+    default:
+      throw new Error(`Unknown unit: ${unit}`);
+  }
+}
+
+/**
+ * Parse timestamp string (Unix timestamp or ISO date)
+ */
+function parseTimestamp(timestamp: string): number {
+  // Unix timestamp (number)
+  if (/^\d+$/.test(timestamp)) {
+    return parseInt(timestamp, 10);
+  }
+
+  // ISO date string
+  const date = new Date(timestamp);
+  if (isNaN(date.getTime())) {
+    throw new Error(
+      `Invalid timestamp: "${timestamp}"\n` +
+        'Expected Unix timestamp or ISO date (e.g., "2025-12-31T23:59:59Z")'
+    );
+  }
+
+  return Math.floor(date.getTime() / 1000);
+}
+
+/**
+ * Format seconds as human-readable duration
+ */
+function formatDuration(seconds: number): string {
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+  if (seconds < 3600) {
+    const minutes = Math.floor(seconds / 60);
+    const secs = seconds % 60;
+    return secs > 0 ? `${minutes}m ${secs}s` : `${minutes}m`;
+  }
+  if (seconds < 86400) {
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  return hours > 0 ? `${days}d ${hours}h` : `${days}d`;
+}
+
+/**
+ * Format timestamp as relative time
+ */
+function formatRelativeTime(timestamp: number): string {
+  const now = Math.floor(Date.now() / 1000);
+  const diff = timestamp - now;
+
+  if (Math.abs(diff) < 60) {
+    return diff >= 0 ? 'just now' : 'just now';
+  }
+
+  const absDiff = Math.abs(diff);
+  const formatted = formatDuration(absDiff);
+
+  if (diff > 0) {
+    return `${formatted} in the future`;
+  } else {
+    return `${formatted} in the past`;
+  }
+}
+
+export { parseDuration, formatDuration };