@agirails/sdk 2.3.1 → 2.4.0

package/src/cli/commands/publish.ts

@@ -1,8 +1,16 @@
 /**
- * Publish Command - Publish AGIRAILS.md config on-chain
+ * Publish Command — Lazy Publish flow.
  *
- * Reads AGIRAILS.md, computes canonical hash, uploads to IPFS,
- * optionally to Arweave, and records on AgentRegistry.
+ * New flow (no on-chain calls):
+ * 1. Parse AGIRAILS.md → compute configHash
+ * 2. Generate wallet if .actp/keystore.json missing
+ * 3. Upload to IPFS via Filebase
+ * 4. Optionally upload to Arweave
+ * 5. Save pending-publish.json (activation deferred to first payment)
+ * 6. Update AGIRAILS.md frontmatter
+ *
+ * On-chain activation happens automatically during the first payment
+ * via ACTPClient's lazy publish mechanism.
  *
  * @module cli/commands/publish
  */
@@ -10,14 +18,68 @@
 import { Command } from 'commander';
 import { Output, ExitCode } from '../utils/output';
 import { mapError } from '../utils/client';
-import { resolve } from 'path';
-import { readFileSync, existsSync } from 'fs';
-import { ethers } from 'ethers';
-import { computeConfigHash, parseAgirailsMd } from '../../config/agirailsmd';
+import { resolve, join } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { computeConfigHash, serializeAgirailsMd, parseAgirailsMd } from '../../config/agirailsmd';
+import { preparePublish, extractRegistrationParams, PENDING_ENDPOINT } from '../../config/publishPipeline';
+import { savePendingPublish, getActpDir } from '../../config/pendingPublish';
+import { addToGitignore, loadConfig, saveConfig, isInitialized, CLIConfig, CONFIG_DEFAULTS } from '../utils/config';
 import { FilebaseClient } from '../../storage/FilebaseClient';
 import { ArweaveClient } from '../../storage/ArweaveClient';
-import { getNetwork } from '../../config/networks';
-import { publishAgirailsMd, PENDING_ENDPOINT } from '../../config/publishPipeline';
+import { generateWallet } from '../utils/wallet';
+
+// ============================================================================
+// Publish Proxy (fallback when no Filebase credentials)
+// ============================================================================
+
+const PUBLISH_PROXY_URL = process.env.AGIRAILS_PUBLISH_URL || 'https://api.agirails.io/v1/publish';
+
+/**
+ * Public client key for the AGIRAILS publish proxy.
+ * This is NOT a secret — it's a rate-limited, revocable identifier
+ * (same model as Firebase API keys). Override via AGIRAILS_PUBLISH_KEY.
+ */
+const PUBLISH_CLIENT_KEY = process.env.AGIRAILS_PUBLISH_KEY || 'ag_pub_v1_2026';
+
+/**
+ * Upload AGIRAILS.md content via the AGIRAILS publish proxy API.
+ * Used when FILEBASE_ACCESS_KEY / FILEBASE_SECRET_KEY are not set.
+ *
+ * @param content - Raw AGIRAILS.md file content
+ * @param localConfigHash - Locally computed configHash (for validation)
+ */
+async function publishViaProxy(content: string, localConfigHash: string): Promise<{ cid: string; configHash: string }> {
+  const response = await fetch(PUBLISH_PROXY_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': PUBLISH_CLIENT_KEY,
+    },
+    body: JSON.stringify({ content }),
+  });
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({ error: response.statusText })) as { error?: string };
+    throw new Error(`Publish proxy error (${response.status}): ${body.error || response.statusText}`);
+  }
+
+  const result = await response.json() as { cid: string; configHash: string };
+  if (!result.cid || !result.configHash) {
+    throw new Error('Publish proxy returned invalid response (missing cid or configHash)');
+  }
+
+  // Validate: proxy's configHash must match locally computed hash
+  // (guards against hash-drift between SDK and API canonicalization logic)
+  if (result.configHash !== localConfigHash) {
+    throw new Error(
+      `Config hash mismatch: proxy returned ${result.configHash.slice(0, 10)}... ` +
+      `but local hash is ${localConfigHash.slice(0, 10)}... — ` +
+      'This may indicate an SDK/API version mismatch. Update your SDK.'
+    );
+  }
+
+  return result;
+}
 
 // ============================================================================
 // Command Definition
@@ -25,9 +87,9 @@ import { publishAgirailsMd, PENDING_ENDPOINT } from '../../config/publishPipelin
 
 export function createPublishCommand(): Command {
   const cmd = new Command('publish')
-    .description('Publish AGIRAILS.md config on-chain')
+    .description('Publish AGIRAILS.md config (offline — activates on first payment)')
     .argument('[path]', 'Path to AGIRAILS.md', './AGIRAILS.md')
-    .option('-n, --network <network>', 'Network (base-sepolia | base-mainnet)', 'base-sepolia')
+    .option('-n, --network <network>', 'DEPRECATED: network is auto-detected (accepted but ignored)')
     .option('--skip-arweave', 'Skip permanent Arweave storage (dev mode)')
     .option('--dry-run', 'Show what would happen without executing')
     .option('--json', 'Output as JSON')
@@ -58,7 +120,7 @@ export function createPublishCommand(): Command {
 // ============================================================================
 
 interface PublishCommandOptions {
-  network: string;
+  network?: string;
   skipArweave?: boolean;
   dryRun?: boolean;
 }
@@ -68,6 +130,11 @@ async function runPublish(
   options: PublishCommandOptions,
   output: Output
 ): Promise<void> {
+  // Deprecation warning for --network
+  if (options.network) {
+    output.warning('--network flag is deprecated and ignored. Network is auto-detected at payment time.');
+  }
+
   const resolvedPath = resolve(filePath);
 
   if (!existsSync(resolvedPath)) {
@@ -91,7 +158,6 @@ async function runPublish(
           structuredHash,
           bodyHash,
           path: resolvedPath,
-          network: options.network,
           dryRun: true,
         },
         { quietKey: 'configHash' }
@@ -102,107 +168,308 @@ async function runPublish(
       return;
     }
 
-    // Validate environment
-    const privateKey = process.env.ACTP_PRIVATE_KEY || process.env.PRIVATE_KEY;
-    if (!privateKey) {
-      spinner.stop(false);
-      output.error('Private key required. Set ACTP_PRIVATE_KEY or PRIVATE_KEY env var.');
-      process.exit(ExitCode.INVALID_INPUT);
+    // Ensure .actp directory exists
+    const actpDir = getActpDir();
+    if (!existsSync(actpDir)) {
+      mkdirSync(actpDir, { recursive: true });
     }
 
-    const networkConfig = getNetwork(options.network);
-    if (!networkConfig.contracts.agentRegistry) {
-      spinner.stop(false);
-      output.error(`AgentRegistry not deployed on ${options.network}`);
-      process.exit(ExitCode.ERROR);
+    // Generate wallet if keystore.json doesn't exist
+    const keystorePath = join(actpDir, 'keystore.json');
+    let walletAddress = '';
+    if (!existsSync(keystorePath)) {
+      spinner.stop(true);
+      output.info('No wallet found — generating one...');
+      walletAddress = await generateWallet(actpDir, output);
+      output.blank();
+    } else {
+      // Read address from existing keystore (plaintext field, no decryption)
+      try {
+        const ks = JSON.parse(readFileSync(keystorePath, 'utf-8'));
+        walletAddress = ks.address ? `0x${ks.address.replace(/^0x/, '')}` : '';
+      } catch {
+        // Best-effort address extraction
+      }
     }
 
-    // Create provider and signer
-    const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
-    const signer = new ethers.Wallet(privateKey, provider);
-
-    // Create Filebase client
+    // Upload to IPFS: direct (Filebase) or via publish proxy
     const filebaseAccessKey = process.env.FILEBASE_ACCESS_KEY;
     const filebaseSecretKey = process.env.FILEBASE_SECRET_KEY;
-    if (!filebaseAccessKey || !filebaseSecretKey) {
-      spinner.stop(false);
-      output.error('Filebase credentials required. Set FILEBASE_ACCESS_KEY and FILEBASE_SECRET_KEY.');
-      process.exit(ExitCode.INVALID_INPUT);
+    const useProxy = !filebaseAccessKey || !filebaseSecretKey;
+
+    spinner.stop(true);
+
+    if (useProxy) {
+      output.info('No Filebase credentials — using AGIRAILS publish proxy.');
     }
 
-    const filebaseClient = new FilebaseClient({
-      accessKey: filebaseAccessKey,
-      secretKey: filebaseSecretKey,
-    });
+    const publishSpinner = output.spinner('Publishing to IPFS...');
 
-    // Create Arweave client (optional)
-    let arweaveClient: ArweaveClient | undefined;
-    if (!options.skipArweave) {
-      const arweaveKey = process.env.ARCHIVE_UPLOADER_KEY;
-      if (arweaveKey) {
-        arweaveClient = await ArweaveClient.create({
-          privateKey: arweaveKey,
-          rpcUrl: networkConfig.rpcUrl,
-        });
+    let cid: string;
+    let arweaveTxId: string | undefined;
+
+    if (useProxy) {
+      // Fallback: upload via AGIRAILS publish proxy API
+      const proxyResult = await publishViaProxy(content, configHash);
+      cid = proxyResult.cid;
+      // Proxy doesn't do Arweave — skip
+    } else {
+      // Direct upload via Filebase S3 + optional Arweave
+      const filebaseClient = new FilebaseClient({
+        accessKey: filebaseAccessKey,
+        secretKey: filebaseSecretKey,
+      });
+
+      let arweaveClient: ArweaveClient | undefined;
+      if (!options.skipArweave) {
+        const arweaveKey = process.env.ARCHIVE_UPLOADER_KEY;
+        if (arweaveKey) {
+          arweaveClient = await ArweaveClient.create({
+            privateKey: arweaveKey,
+            rpcUrl: 'https://mainnet.base.org',
+          });
+        }
       }
-    }
 
-    spinner.stop(true);
-    const publishSpinner = output.spinner('Publishing to IPFS + on-chain...');
-
-    const result = await publishAgirailsMd({
-      path: resolvedPath,
-      network: options.network,
-      registryAddress: networkConfig.contracts.agentRegistry,
-      signer,
-      filebaseClient,
-      arweaveClient,
-      skipArweave: options.skipArweave || !arweaveClient,
-      gasSettings: {
-        maxFeePerGas: networkConfig.gasSettings.maxFeePerGas,
-        maxPriorityFeePerGas: networkConfig.gasSettings.maxPriorityFeePerGas,
-      },
-    });
+      const prepResult = await preparePublish({
+        path: resolvedPath,
+        filebaseClient,
+        arweaveClient,
+        skipArweave: options.skipArweave || !arweaveClient,
+      });
+
+      cid = prepResult.cid;
+      arweaveTxId = prepResult.arweaveTxId;
+    }
 
     publishSpinner.stop(true);
 
+    // Parse frontmatter for registration params
+    const { frontmatter, body } = parseAgirailsMd(content);
+    const regParams = extractRegistrationParams(frontmatter as Record<string, unknown>);
+
+    const pendingData = {
+      version: 1 as const,
+      configHash,
+      cid,
+      endpoint: regParams.endpoint,
+      serviceDescriptors: regParams.serviceDescriptors,
+      createdAt: new Date().toISOString(),
+    };
+
+    const projectRoot = resolve(filePath, '..');
+
+    // ================================================================
+    // Local setup: bootstrap or migrate config, ensure .gitignore
+    // "publish covers setup" — no separate `actp init` required.
+    // ================================================================
+    try {
+      if (isInitialized(projectRoot)) {
+        // Existing project: migrate config (strip deprecated `registered`)
+        const config = loadConfig(projectRoot);
+        saveConfig(config, projectRoot);
+      } else if (walletAddress) {
+        // Fresh project: bootstrap minimal config using address from keystore
+        const bootstrapConfig: CLIConfig = {
+          ...CONFIG_DEFAULTS,
+          mode: 'testnet', // safe default for new projects
+          address: walletAddress.toLowerCase(),
+          wallet: 'auto',
+          version: '1.0',
+        };
+        saveConfig(bootstrapConfig, projectRoot);
+        output.info('Created .actp/config.json (testnet, auto wallet).');
+      }
+    } catch {
+      // Config setup is best-effort — publish works without it
+    }
+    addToGitignore(projectRoot);
+
+    // ================================================================
+    // ALWAYS activate on testnet (one command, both networks per SPEC)
+    // ================================================================
+    let testnetTxHash: string | undefined;
+    const activationSpinner = output.spinner('Activating on testnet...');
+    try {
+      testnetTxHash = await activateOnTestnet(
+        projectRoot, configHash, cid,
+        regParams.endpoint, regParams.serviceDescriptors, output,
+      );
+      activationSpinner.stop(true);
+      if (testnetTxHash) {
+        output.success(`Testnet activation: ${testnetTxHash}`);
+      } else {
+        output.info('Testnet: already up-to-date.');
+      }
+    } catch (activationError) {
+      activationSpinner.stop(false);
+      // Save testnet pending as fallback — will activate on first testnet payment
+      savePendingPublish({ ...pendingData, network: 'base-sepolia' });
+      output.warning(
+        `Testnet activation failed: ${(activationError as Error).message}\n` +
+        '  Saved as pending — will activate on first testnet payment.'
+      );
+    }
+
+    // Always save mainnet pending (lazy — activates on first mainnet payment)
+    savePendingPublish({ ...pendingData, network: 'base-mainnet' });
+
+    // Update AGIRAILS.md frontmatter
+    const updatedFrontmatter = {
+      ...(frontmatter as Record<string, unknown>),
+      config_hash: configHash,
+      config_cid: cid,
+      published_at: new Date().toISOString(),
+      ...(arweaveTxId ? { arweave_tx: arweaveTxId } : {}),
+    };
+    const updatedContent = serializeAgirailsMd(updatedFrontmatter, body);
+    writeFileSync(resolvedPath, updatedContent, 'utf-8');
+
+    // Output results
     output.result(
       {
-        configHash: result.configHash,
-        cid: result.cid,
-        txHash: result.txHash,
-        arweaveTxId: result.arweaveTxId || null,
-        registered: result.registered || false,
-        network: options.network,
+        configHash,
+        cid,
+        arweaveTxId: arweaveTxId || null,
+        pendingPublish: true,
+        testnetActivated: !!testnetTxHash,
+        ...(testnetTxHash ? { testnetTxHash } : {}),
       },
       { quietKey: 'configHash' }
     );
 
     output.blank();
-    if (result.registered) {
-      output.success('Agent registered and config published!');
-    } else {
-      output.success('Config published successfully!');
+    output.success('Config published to IPFS and saved locally.');
+
+    if (testnetTxHash) {
+      output.print('');
+      output.success('Testnet: activated on-chain.');
     }
+
+    output.print('');
+    output.print('Mainnet: on-chain activation will happen on your first payment.');
     output.print('');
     output.print('Next steps:');
-    output.print('  - Verify sync:  actp diff');
-    output.print('  - View on-chain: ' + networkConfig.blockExplorer + '/tx/' + result.txHash);
-
-    // Warn if placeholder endpoint was used during auto-register
-    if (result.registered) {
-      const content = readFileSync(resolvedPath, 'utf-8');
-      const { frontmatter } = parseAgirailsMd(content);
-      if (!frontmatter.endpoint || frontmatter.endpoint === PENDING_ENDPOINT) {
-        output.print('');
-        output.warning('No endpoint in AGIRAILS.md — registered with placeholder URL.');
-        output.print('  Update when your agent is deployed:');
-        output.print('    1. Add "endpoint: https://your-agent.com/webhook" to AGIRAILS.md');
-        output.print('    2. Run: actp publish');
-      }
+    output.print('  - Verify config:  actp diff');
+    output.print('  - Make a payment: your first mainnet payment activates the agent on-chain');
+
+    // Warn if placeholder endpoint
+    if (!frontmatter.endpoint || frontmatter.endpoint === PENDING_ENDPOINT) {
+      output.print('');
+      output.warning('No endpoint in AGIRAILS.md — using placeholder URL.');
+      output.print('  Update when your agent is deployed:');
+      output.print('    1. Add "endpoint: https://your-agent.com/webhook" to AGIRAILS.md');
+      output.print('    2. Run: actp publish');
     }
   } catch (error) {
     spinner.stop(false);
     throw error;
   }
 }
+
+// ============================================================================
+// Testnet Activation
+// ============================================================================
+
+/**
+ * Activate agent on testnet during `actp publish`.
+ *
+ * SPEC v4 Step 3: activation + mint test USDC in a single gasless UserOp.
+ * Always mints test USDC regardless of scenario (SPEC: "always on testnet").
+ *
+ * @returns Transaction hash of the UserOp, or undefined if already up-to-date
+ */
+async function activateOnTestnet(
+  projectRoot: string,
+  configHash: string,
+  cid: string,
+  endpoint: string,
+  serviceDescriptors: import('../../types/agent').ServiceDescriptor[],
+  output: Output,
+): Promise<string | undefined> {
+  const { resolvePrivateKey } = await import('../../wallet/keystore');
+  const { ethers } = await import('ethers');
+  const { getNetwork } = await import('../../config/networks');
+  const { AutoWalletProvider } = await import('../../wallet/AutoWalletProvider');
+  const { buildActivationBatch, buildTestnetMintBatch } = await import('../../wallet/aa/TransactionBatcher');
+  const { getOnChainAgentState, detectLazyPublishScenario } = await import('../../ACTPClient');
+
+  const privateKey = await resolvePrivateKey(projectRoot);
+  if (!privateKey) {
+    throw new Error('No wallet found. Cannot activate on testnet.');
+  }
+
+  const networkConfig = getNetwork('base-sepolia');
+  if (!networkConfig.aa || !networkConfig.contracts.agentRegistry) {
+    throw new Error('Testnet AA or AgentRegistry not configured.');
+  }
+
+  const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
+  const signer = new ethers.Wallet(privateKey, provider);
+
+  const autoWallet = await AutoWalletProvider.create({
+    signer,
+    provider,
+    chainId: networkConfig.chainId,
+    actpKernelAddress: networkConfig.contracts.actpKernel,
+    bundler: {
+      primaryUrl: networkConfig.aa.bundlerUrls.coinbase,
+      backupUrl: networkConfig.aa.bundlerUrls.pimlico,
+    },
+    paymaster: {
+      primaryUrl: networkConfig.aa.paymasterUrls.coinbase,
+      backupUrl: networkConfig.aa.paymasterUrls.pimlico,
+    },
+  });
+
+  const smartWalletAddress = autoWallet.getAddress();
+  output.info(`Smart Wallet: ${smartWalletAddress}`);
+
+  // Check on-chain state to determine activation scenario
+  const onChainState = await getOnChainAgentState(
+    provider, networkConfig.contracts.agentRegistry, smartWalletAddress
+  );
+  const scenario = detectLazyPublishScenario(onChainState, {
+    version: 1, configHash, cid, endpoint, serviceDescriptors, createdAt: new Date().toISOString(),
+  });
+
+  if (scenario === 'C' || scenario === 'none') {
+    // Already up-to-date on-chain — no activation needed
+    return undefined;
+  }
+
+  // Build activation calls
+  const activationCalls = buildActivationBatch({
+    scenario,
+    agentRegistryAddress: networkConfig.contracts.agentRegistry,
+    cid,
+    configHash,
+    listed: true,
+    ...(scenario === 'A' ? { endpoint, serviceDescriptors } : {}),
+  });
+
+  // Always mint test USDC on testnet (SPEC: "always")
+  const mintCalls = buildTestnetMintBatch(
+    networkConfig.contracts.usdc,
+    smartWalletAddress,
+    '1000000000', // 1000 USDC
+  );
+
+  const allCalls = [...activationCalls, ...mintCalls];
+  const txRequests = allCalls.map((c) => ({
+    to: c.target,
+    data: c.data,
+    value: c.value.toString(),
+  }));
+
+  output.info(`Submitting ${allCalls.length}-call UserOp...`);
+  const receipt = await autoWallet.sendBatchTransaction(txRequests);
+
+  if (!receipt.success) {
+    throw new Error(`Testnet activation UserOp failed: ${receipt.hash}`);
+  }
+
+  output.success('Minted 1,000 test USDC to Smart Wallet');
+  return receipt.hash;
+}
+

package/src/cli/commands/register.ts

@@ -27,6 +27,7 @@ export function createRegisterCommand(): Command {
   const cmd = new Command('register')
     .description('Register agent on AgentRegistry for gas-free transactions')
     .option('--endpoint <url>', 'Service endpoint URL (overrides AGIRAILS.md)')
+    .option('--force-legacy', 'Bypass deprecation and run legacy registration')
     .option('--json', 'Output as JSON')
     .option('-q, --quiet', 'Minimal output')
     .action(async (options) => {
@@ -34,6 +35,19 @@ export function createRegisterCommand(): Command {
         options.json ? 'json' : options.quiet ? 'quiet' : 'human'
       );
 
+      // Deprecation warning
+      output.warning(
+        'DEPRECATED: "actp register" is deprecated. Use "actp publish" instead.\n' +
+        '  "actp publish" saves config locally. On-chain activation happens\n' +
+        '  automatically on your first payment (lazy publish).'
+      );
+      output.blank();
+
+      if (!options.forceLegacy) {
+        output.print('To proceed anyway, use: actp register --force-legacy');
+        return;
+      }
+
       try {
         await runRegister(options, output);
       } catch (error) {

package/src/cli/utils/config.ts

@@ -38,7 +38,7 @@ export interface CLIConfig {
   /** AIP-12: Wallet type — 'auto' (Smart Wallet, gasless) or 'eoa' (traditional) */
   wallet?: 'auto' | 'eoa';
 
-  /** AIP-12: Smart Wallet address (set when wallet=auto, used by `actp register`) */
+  /** AIP-12: Smart Wallet address (set when wallet=auto, used by `actp publish`) */
   smartWallet?: string;
 
   /** AIP-12: Whether agent is registered on AgentRegistry */
@@ -46,6 +46,27 @@ export interface CLIConfig {
 
   /** Configuration version for migrations */
   version: string;
+
+  /** Agent name from AGIRAILS.md */
+  agentName?: string;
+
+  /** Agent intent: earn, pay, or both */
+  intent?: 'earn' | 'pay' | 'both';
+
+  /** Service capabilities from AGIRAILS.md */
+  capabilities?: string[];
+
+  /** Base price in USDC */
+  price?: number;
+
+  /** Max concurrent jobs */
+  concurrency?: number;
+
+  /** Payment mode: actp, x402, or both */
+  paymentMode?: 'actp' | 'x402' | 'both';
+
+  /** Budget cap in USDC */
+  budget?: number;
 }
 
 /**
@@ -62,9 +83,13 @@ export const CONFIG_DEFAULTS: CLIConfig = {
 // ============================================================================
 
 /**
- * Get the .actp directory path
+ * Get the .actp directory path.
+ * Respects ACTP_DIR env var override for custom locations.
  */
 export function getActpDir(projectRoot: string = process.cwd()): string {
+  if (process.env.ACTP_DIR) {
+    return process.env.ACTP_DIR;
+  }
   return path.join(projectRoot, '.actp');
 }
 
@@ -122,6 +147,11 @@ export function loadConfig(projectRoot: string = process.cwd()): CLIConfig {
       console.warn('\x1b[33m%s\x1b[0m', '         Run: export ACTP_PRIVATE_KEY=<your-key>');
     }
 
+    // Config migration: strip deprecated `registered` field (lazy publish)
+    if ('registered' in config) {
+      delete (config as unknown as Record<string, unknown>).registered;
+    }
+
     return config;
   } catch (error) {
     if (error instanceof SyntaxError) {