@agirails/sdk 2.2.0 → 2.2.2

package/src/cli/commands/init.ts

@@ -8,6 +8,8 @@
  */
 
 import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
 import { Command } from 'commander';
 import {
   saveConfig,
@@ -30,6 +32,10 @@ export function createInitCommand(): Command {
     .option('-m, --mode <mode>', 'Operating mode: mock, testnet, mainnet', 'mock')
     .option('-a, --address <address>', 'Your Ethereum address')
     .option('-f, --force', 'Overwrite existing configuration')
+    .option('--scaffold', 'Generate a starter agent.ts file')
+    .option('--intent <intent>', 'Agent intent: earn, pay, or both (default: earn)')
+    .option('--service <name>', 'Service name (default: my-service)')
+    .option('--price <usdc>', 'Base price in USDC (default: 1)')
     .option('--json', 'Output as JSON')
     .option('-q, --quiet', 'Minimal output')
     .action(async (options) => {
@@ -55,10 +61,16 @@ export function createInitCommand(): Command {
 // Implementation
 // ============================================================================
 
+type ScaffoldIntent = 'earn' | 'pay' | 'both';
+
 interface InitOptions {
   mode: string;
   address?: string;
   force?: boolean;
+  scaffold?: boolean;
+  intent?: string;
+  service?: string;
+  price?: string;
 }
 
 async function runInit(options: InitOptions, output: Output): Promise<void> {
@@ -151,11 +163,204 @@ async function runInit(options: InitOptions, output: Output): Promise<void> {
     { quietKey: 'address' }
   );
 
+  // Generate scaffold if requested
+  if (options.scaffold) {
+    await runScaffold(options, mode, output);
+  } else {
+    output.blank();
+    output.print('Next steps:');
+    output.print('  1. Create a payment: actp pay <provider> <amount>');
+    output.print('  2. Check your balance: actp balance');
+    output.print('  3. List transactions: actp tx list');
+    output.print('');
+    output.print('Tip: Use --scaffold to generate a starter agent.ts');
+  }
+}
+
+// ============================================================================
+// Scaffold
+// ============================================================================
+
+async function runScaffold(
+  options: InitOptions,
+  mode: CLIMode,
+  output: Output,
+): Promise<void> {
+  const validIntents: ScaffoldIntent[] = ['earn', 'pay', 'both'];
+  const intent: ScaffoldIntent = (options.intent as ScaffoldIntent) || 'earn';
+
+  if (!validIntents.includes(intent)) {
+    throw new Error(
+      `Invalid intent: "${options.intent}". Valid intents: ${validIntents.join(', ')}`
+    );
+  }
+
+  const service = options.service || 'my-service';
+  const price = options.price || '1';
+  const agentFile = path.join(process.cwd(), 'agent.ts');
+
+  // Check if file already exists
+  if (fs.existsSync(agentFile) && !options.force) {
+    output.warning('agent.ts already exists. Use --force to overwrite.');
+    return;
+  }
+
+  // Derive agent name from directory
+  const agentName = path.basename(process.cwd());
+
+  // Get template and substitute variables
+  const template = getTemplate(intent);
+  const content = template
+    .replace(/\{\{service\}\}/g, service)
+    .replace(/\{\{mode\}\}/g, mode)
+    .replace(/\{\{price\}\}/g, price)
+    .replace(/\{\{name\}\}/g, agentName);
+
+  // Atomic write
+  const tempFile = `${agentFile}.tmp`;
+  try {
+    fs.writeFileSync(tempFile, content, 'utf-8');
+    fs.renameSync(tempFile, agentFile);
+  } catch (error) {
+    if (fs.existsSync(tempFile)) {
+      try { fs.unlinkSync(tempFile); } catch { /* ignore */ }
+    }
+    throw error;
+  }
+
+  output.success(`Generated agent.ts (intent: ${intent})`);
+
+  // Generate tsconfig.json if it doesn't exist
+  const tsconfigFile = path.join(process.cwd(), 'tsconfig.json');
+  if (!fs.existsSync(tsconfigFile)) {
+    const tsconfigContent = JSON.stringify({
+      compilerOptions: {
+        target: 'ES2022',
+        module: 'ES2022',
+        moduleResolution: 'bundler',
+        esModuleInterop: true,
+        strict: true,
+        outDir: 'dist',
+        skipLibCheck: true,
+      },
+      include: ['*.ts'],
+    }, null, 2);
+
+    const tsconfigTemp = `${tsconfigFile}.tmp`;
+    try {
+      fs.writeFileSync(tsconfigTemp, tsconfigContent, 'utf-8');
+      fs.renameSync(tsconfigTemp, tsconfigFile);
+      output.success('Generated tsconfig.json');
+    } catch {
+      output.warning('Could not generate tsconfig.json');
+    }
+  }
+
+  // Check package.json for type: module
+  const pkgFile = path.join(process.cwd(), 'package.json');
+  if (fs.existsSync(pkgFile)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+      if (pkg.type !== 'module') {
+        output.warning(
+          'package.json has type: "' + (pkg.type || 'commonjs') + '". ' +
+          'Set "type": "module" for ESM support, or run with: npx ts-node --esm agent.ts'
+        );
+      }
+    } catch { /* ignore parse errors */ }
+  }
+
   output.blank();
   output.print('Next steps:');
-  output.print('  1. Create a payment: actp pay <provider> <amount>');
-  output.print('  2. Check your balance: actp balance');
-  output.print('  3. List transactions: actp tx list');
+  output.print('  1. Edit agent.ts with your logic');
+  output.print('  2. Run: npx ts-node --esm agent.ts');
+  output.print('  3. Check balance: actp balance');
+}
+
+function getTemplate(intent: ScaffoldIntent): string {
+  switch (intent) {
+    case 'earn':
+      return TEMPLATE_EARN;
+    case 'pay':
+      return TEMPLATE_PAY;
+    case 'both':
+      return TEMPLATE_BOTH;
+  }
+}
+
+// ============================================================================
+// Templates
+// ============================================================================
+
+const TEMPLATE_EARN = `import { provide } from '@agirails/sdk';
+
+const provider = provide('{{service}}', async (job) => {
+  console.log(\`Job received: \${job.id} (\${job.budget} USDC)\`);
+
+  // TODO: Replace with your actual work
+  const result = await processJob(job.input);
+
+  return result;
+}, {
+  network: '{{mode}}',
+  filter: { minBudget: {{price}} },
+});
+
+async function processJob(input: any): Promise<any> {
+  // Your logic here
+  return { status: 'completed', output: input };
+}
+
+console.log(\`Provider listening for '{{service}}' jobs...\`);
+`;
+
+const TEMPLATE_PAY = `import { request } from '@agirails/sdk';
+
+async function main() {
+  const { result, transaction } = await request('{{service}}', {
+    provider: '0xPROVIDER_ADDRESS', // replace with the provider's address
+    input: { /* your data here */ },
+    budget: {{price}},
+    network: '{{mode}}',
+  });
+
+  console.log('Result:', result);
+  console.log('Transaction:', transaction.id);
+  console.log('Fee:', transaction.fee, 'USDC');
+}
+
+main().catch(console.error);
+`;
+
+const TEMPLATE_BOTH = `import { Agent } from '@agirails/sdk';
+
+async function main() {
+  const agent = new Agent({
+    name: '{{name}}',
+    network: '{{mode}}',
+    behavior: {
+      autoAccept: true,
+      concurrency: 10,
+    },
+  });
+
+  // Provide a service
+  agent.provide('{{service}}', async (job, ctx) => {
+    ctx.progress(50, 'Working...');
+
+    // TODO: Replace with your actual work
+    return { status: 'completed', output: job.input };
+  });
+
+  agent.on('payment:received', (data) => {
+    console.log(\`Earned \${data.amount} USDC\`);
+  });
+
+  await agent.start();
+  console.log(\`Agent '{{name}}' running on {{mode}}\`);
 }
 
+main().catch(console.error);
+`;
+
 export { runInit };

package/src/config/networks.ts

@@ -58,9 +58,9 @@ export const BASE_SEPOLIA: NetworkConfig = {
   rpcUrl: BASE_SEPOLIA_RPC_URL,
   blockExplorer: 'https://sepolia.basescan.org',
   contracts: {
-    // Redeployed 2025-12-10
-    actpKernel: '0xD199070F8e9FB9a127F6Fe730Bc13300B4b3d962',
-    escrowVault: '0x948b9Ea081C4Cec1E112Af2e539224c531d4d585',
+    // Redeployed 2026-02-06 with agentId support
+    actpKernel: '0x469CBADbACFFE096270594F0a31f0EEC53753411',
+    escrowVault: '0x57f888261b629bB380dfb983f5DA6c70Ff2D49E5',
     usdc: '0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb', // MockUSDC
     // EAS contracts (Base native deployment)
     eas: '0x4200000000000000000000000000000000000021',

package/src/erc8004/ERC8004Bridge.ts

@@ -0,0 +1,461 @@
+/**
+ * ERC-8004 Identity Bridge
+ *
+ * READ-ONLY access to ERC-8004 Identity Registry.
+ * Resolves agent IDs to wallet addresses for ACTP payments.
+ *
+ * SECURITY NOTES:
+ * - All operations are view functions (no gas costs)
+ * - Safe to call without signer
+ * - Caches results to minimize RPC calls
+ * - Handles network errors gracefully
+ *
+ * @example
+ * ```typescript
+ * const bridge = new ERC8004Bridge({ network: 'base-sepolia' });
+ *
+ * // Check if agent exists
+ * const exists = await bridge.verifyAgent('12345');
+ *
+ * // Get wallet for payment
+ * const wallet = await bridge.getAgentWallet('12345');
+ *
+ * // Get full agent info
+ * const agent = await bridge.resolveAgent('12345');
+ * ```
+ *
+ * @module erc8004/ERC8004Bridge
+ */
+
+import { ethers } from 'ethers';
+import {
+  ERC8004Agent,
+  ERC8004AgentMetadata,
+  ERC8004Network,
+  ERC8004Error,
+  ERC8004ErrorCode,
+  ERC8004_IDENTITY_REGISTRY,
+  ERC8004_IDENTITY_ABI,
+  ERC8004_DEFAULT_RPC,
+} from '../types/erc8004';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Interface for ERC-8004 Identity Registry contract.
+ * Used for testing with mock implementations.
+ */
+export interface IERC8004IdentityRegistry {
+  ownerOf(agentId: string): Promise<string>;
+  getAgentURI(agentId: string): Promise<string>;
+  balanceOf(owner: string): Promise<bigint>;
+  tokenOfOwnerByIndex(owner: string, index: number): Promise<bigint>;
+}
+
+/**
+ * Configuration for ERC8004Bridge.
+ */
+export interface ERC8004BridgeConfig {
+  /** Target network */
+  network: ERC8004Network;
+
+  /** Custom RPC URL (optional, uses default if not provided) */
+  rpcUrl?: string;
+
+  /** Override registry address (optional, for testing) */
+  registryAddress?: string;
+
+  /** Custom fetch function (optional, for testing) */
+  fetchFn?: typeof fetch;
+
+  /** Cache TTL in milliseconds (default: 60000 = 1 minute) */
+  cacheTimeMs?: number;
+
+  /** Metadata fetch timeout in milliseconds (default: 10000 = 10 seconds) */
+  metadataTimeoutMs?: number;
+
+  /**
+   * Injected contract instance (optional, for testing).
+   * If provided, skips creating a real ethers Contract.
+   * @internal
+   */
+  _testContract?: IERC8004IdentityRegistry;
+}
+
+/**
+ * Cached agent entry.
+ */
+interface CachedAgent {
+  agent: ERC8004Agent;
+  expiresAt: number;
+}
+
+// ============================================================================
+// ERC8004Bridge
+// ============================================================================
+
+/**
+ * Bridge for reading from ERC-8004 Identity Registry.
+ *
+ * Provides methods to:
+ * - Verify agent existence
+ * - Get agent wallet address for payments
+ * - Resolve full agent info including metadata
+ * - List agents owned by an address
+ */
+export class ERC8004Bridge {
+  private readonly provider: ethers.JsonRpcProvider | null;
+  private readonly registry: IERC8004IdentityRegistry;
+  private readonly cache: Map<string, CachedAgent>;
+  private readonly fetchFn: typeof fetch;
+  private readonly cacheTimeMs: number;
+  private readonly metadataTimeoutMs: number;
+  private readonly network: ERC8004Network;
+
+  constructor(config: ERC8004BridgeConfig) {
+    this.network = config.network;
+    this.fetchFn = config.fetchFn ?? fetch;
+    this.cacheTimeMs = config.cacheTimeMs ?? 60000;
+    this.metadataTimeoutMs = config.metadataTimeoutMs ?? 10000;
+    this.cache = new Map();
+
+    // Use injected contract for testing
+    if (config._testContract) {
+      this.provider = null;
+      this.registry = config._testContract;
+      return;
+    }
+
+    // Setup provider
+    const rpcUrl = config.rpcUrl ?? ERC8004_DEFAULT_RPC[config.network];
+    this.provider = new ethers.JsonRpcProvider(rpcUrl);
+
+    // Setup registry contract
+    const registryAddress =
+      config.registryAddress ?? ERC8004_IDENTITY_REGISTRY[config.network];
+
+    if (registryAddress === ethers.ZeroAddress) {
+      console.warn(
+        `[ERC8004] Registry not deployed on ${config.network}. Using zero address.`
+      );
+    }
+
+    this.registry = new ethers.Contract(
+      registryAddress,
+      ERC8004_IDENTITY_ABI,
+      this.provider
+    ) as unknown as IERC8004IdentityRegistry;
+  }
+
+  // ==========================================================================
+  // Public Methods
+  // ==========================================================================
+
+  /**
+   * Verify agent exists in ERC-8004 Identity Registry.
+   *
+   * Safe to call frequently - uses cache and is a view function.
+   *
+   * @param agentId - ERC-8004 agent ID (uint256 as string)
+   * @returns true if agent exists, false otherwise
+   */
+  async verifyAgent(agentId: string): Promise<boolean> {
+    // Validate format first
+    if (!this.isValidAgentId(agentId)) {
+      return false;
+    }
+
+    // Check cache
+    const cached = this.cache.get(agentId);
+    if (cached && cached.expiresAt > Date.now()) {
+      return true;
+    }
+
+    try {
+      const owner = await this.registry.ownerOf(agentId);
+      return owner !== ethers.ZeroAddress;
+    } catch {
+      // ownerOf reverts for non-existent tokens (ERC-721 standard)
+      return false;
+    }
+  }
+
+  /**
+   * Get wallet address for receiving payments.
+   *
+   * Wallet priority:
+   * 1. metadata.paymentAddress (explicit payment destination)
+   * 2. metadata.wallet (alternative field name)
+   * 3. owner address (fallback)
+   *
+   * @param agentId - ERC-8004 agent ID
+   * @returns Checksummed wallet address
+   * @throws ERC8004Error if agent not found
+   */
+  async getAgentWallet(agentId: string): Promise<string> {
+    const agent = await this.resolveAgent(agentId);
+    return agent.wallet;
+  }
+
+  /**
+   * Resolve full agent info from ERC-8004.
+   *
+   * Fetches on-chain data (owner, agentURI) and off-chain metadata.
+   * Results are cached for cacheTimeMs.
+   *
+   * @param agentId - ERC-8004 agent ID
+   * @returns Full agent info including metadata
+   * @throws ERC8004Error if agent not found or invalid ID
+   */
+  async resolveAgent(agentId: string): Promise<ERC8004Agent> {
+    // Check cache first
+    const cached = this.cache.get(agentId);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.agent;
+    }
+
+    // Validate format
+    if (!this.isValidAgentId(agentId)) {
+      throw new ERC8004Error(
+        `Invalid agent ID format: "${agentId}"`,
+        ERC8004ErrorCode.INVALID_AGENT_ID,
+        agentId
+      );
+    }
+
+    // Fetch on-chain data
+    let owner: string;
+    let agentURI: string;
+
+    try {
+      [owner, agentURI] = await Promise.all([
+        this.registry.ownerOf(agentId),
+        this.registry.getAgentURI(agentId),
+      ]);
+    } catch (error) {
+      // Check if it's a "nonexistent token" error
+      const isNotFound =
+        error instanceof Error &&
+        (error.message.includes('nonexistent') ||
+          error.message.includes('ERC721') ||
+          error.message.includes('invalid token'));
+
+      if (isNotFound) {
+        throw new ERC8004Error(
+          `Agent ${agentId} not found in ERC-8004 registry`,
+          ERC8004ErrorCode.AGENT_NOT_FOUND,
+          agentId
+        );
+      }
+
+      throw new ERC8004Error(
+        `Failed to fetch agent ${agentId}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        ERC8004ErrorCode.NETWORK_ERROR,
+        agentId,
+        error instanceof Error ? error : undefined
+      );
+    }
+
+    // Check owner is valid
+    if (owner === ethers.ZeroAddress) {
+      throw new ERC8004Error(
+        `Agent ${agentId} not found in ERC-8004 registry`,
+        ERC8004ErrorCode.AGENT_NOT_FOUND,
+        agentId
+      );
+    }
+
+    // Fetch metadata (may return undefined if fetch fails)
+    const metadata = await this.fetchMetadata(agentURI, agentId);
+
+    // Determine wallet address
+    // Priority: paymentAddress > wallet > owner
+    let walletAddress = owner;
+
+    if (metadata?.paymentAddress && this.isValidAddress(metadata.paymentAddress)) {
+      walletAddress = metadata.paymentAddress;
+    } else if (metadata?.wallet && this.isValidAddress(metadata.wallet)) {
+      walletAddress = metadata.wallet;
+    }
+
+    // Build agent object
+    const agent: ERC8004Agent = {
+      agentId,
+      owner: ethers.getAddress(owner), // Checksummed
+      wallet: ethers.getAddress(walletAddress), // Checksummed
+      agentURI,
+      metadata,
+      network: this.network,
+    };
+
+    // Cache result
+    this.cache.set(agentId, {
+      agent,
+      expiresAt: Date.now() + this.cacheTimeMs,
+    });
+
+    return agent;
+  }
+
+  /**
+   * Get all agent IDs owned by an address.
+   *
+   * @param owner - Owner address to query
+   * @returns Array of agent IDs (may be empty)
+   */
+  async getAgentsByOwner(owner: string): Promise<string[]> {
+    if (!this.isValidAddress(owner)) {
+      return [];
+    }
+
+    try {
+      const balance = await this.registry.balanceOf(owner);
+      const balanceNum = Number(balance);
+
+      if (balanceNum === 0) {
+        return [];
+      }
+
+      const agentIds: string[] = [];
+
+      for (let i = 0; i < balanceNum; i++) {
+        const agentId = await this.registry.tokenOfOwnerByIndex(owner, i);
+        agentIds.push(agentId.toString());
+      }
+
+      return agentIds;
+    } catch (error) {
+      console.warn(`[ERC8004] Failed to get agents for owner ${owner}:`, error);
+      return [];
+    }
+  }
+
+  /**
+   * Clear all cached entries.
+   * Useful for testing or forcing fresh data.
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics (for debugging).
+   */
+  getCacheStats(): { size: number; network: ERC8004Network } {
+    return {
+      size: this.cache.size,
+      network: this.network,
+    };
+  }
+
+  // ==========================================================================
+  // Private Methods
+  // ==========================================================================
+
+  /**
+   * Validate agent ID format.
+   * Agent IDs are uint256 values (0 to 2^256-1).
+   */
+  private isValidAgentId(agentId: string): boolean {
+    if (!agentId || typeof agentId !== 'string') {
+      return false;
+    }
+
+    // Must not look like an Ethereum address or URL
+    if (agentId.startsWith('0x') || agentId.includes('://')) {
+      return false;
+    }
+
+    try {
+      const bn = BigInt(agentId);
+      return bn >= 0n && bn < 2n ** 256n;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Validate Ethereum address format.
+   */
+  private isValidAddress(address: string): boolean {
+    try {
+      ethers.getAddress(address);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Fetch and parse metadata from agentURI.
+   *
+   * Handles:
+   * - IPFS URIs (ipfs://...)
+   * - HTTPS URIs
+   * - Timeout protection
+   * - Parse errors
+   *
+   * Returns undefined on any failure (never throws).
+   */
+  private async fetchMetadata(
+    agentURI: string,
+    agentId: string
+  ): Promise<ERC8004AgentMetadata | undefined> {
+    if (!agentURI) {
+      return undefined;
+    }
+
+    try {
+      // Convert IPFS URI to HTTP gateway
+      let url = agentURI;
+      if (url.startsWith('ipfs://')) {
+        const cid = url.slice(7);
+        url = `https://ipfs.io/ipfs/${cid}`;
+      }
+
+      // Validate URL
+      if (!url.startsWith('http://') && !url.startsWith('https://')) {
+        console.warn(`[ERC8004] Invalid agentURI scheme for ${agentId}: ${url}`);
+        return undefined;
+      }
+
+      // Fetch with timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.metadataTimeoutMs);
+
+      try {
+        const response = await this.fetchFn(url, {
+          headers: { Accept: 'application/json' },
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+          console.warn(
+            `[ERC8004] Metadata fetch failed for ${agentId}: HTTP ${response.status}`
+          );
+          return undefined;
+        }
+
+        const data = await response.json();
+        return data as ERC8004AgentMetadata;
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (error) {
+      // Log but don't throw - metadata is optional
+      const errorMessage =
+        error instanceof Error
+          ? error.name === 'AbortError'
+            ? 'timeout'
+            : error.message
+          : 'unknown error';
+
+      console.warn(`[ERC8004] Metadata fetch failed for ${agentId}: ${errorMessage}`);
+      return undefined;
+    }
+  }
+}