@agirails/sdk 2.3.1 → 2.4.0

package/src/ACTPClient.ts

@@ -11,10 +11,9 @@
  *
  * @example
  * ```typescript
- * // Create client in mock mode
+ * // Create client (auto-detects wallet from .actp/keystore.json or env vars)
  * const client = await ACTPClient.create({
  *   mode: 'mock',
- *   requesterAddress: '0x1234...',
  * });
  *
  * // Basic API - simplest approach
@@ -57,6 +56,9 @@ import { getNetwork } from './config/networks';
 import { IWalletProvider } from './wallet/IWalletProvider';
 import { EOAWalletProvider } from './wallet/EOAWalletProvider';
 import { AutoWalletProvider } from './wallet/AutoWalletProvider';
+import { SmartWalletCall } from './wallet/aa/constants';
+import { buildActivationBatch, ActivationScenario } from './wallet/aa/TransactionBatcher';
+import { loadPendingPublish, deletePendingPublish, PendingPublish } from './config/pendingPublish';
 import { sdkLogger } from './utils/Logger';
 
 // ============================================================================
@@ -74,18 +76,24 @@ import { sdkLogger } from './utils/Logger';
  * @param stateDirectory - The directory path to validate
  * @throws Error if path is unsafe
  */
+/** On-chain agent state from AgentRegistry. */
+export interface OnChainAgentState {
+  registeredAt: bigint;
+  configHash: string;
+  listed: boolean;
+}
+
+const ZERO_HASH = '0x' + '0'.repeat(64);
+
 /**
- * Check if an agent is registered on AgentRegistry.
- * Lightweight read-only check — no signer needed.
- *
- * Uses minimal ABI fragment to avoid importing the full AgentRegistry class.
- * Checks registeredAt field of AgentProfile struct (> 0 means registered).
+ * Read the on-chain agent state from AgentRegistry.
+ * Returns registeredAt, configHash, and listed fields.
  */
-async function checkRegistration(
+export async function getOnChainAgentState(
   provider: ethers.JsonRpcProvider,
   registryAddress: string,
   agentAddress: string
-): Promise<boolean> {
+): Promise<OnChainAgentState> {
   const contract = new ethers.Contract(
     registryAddress,
     [
@@ -98,7 +106,46 @@ async function checkRegistration(
     provider
   );
   const profile = await contract.getAgent(agentAddress);
-  return profile.registeredAt > 0n;
+  return {
+    registeredAt: profile.registeredAt,
+    configHash: profile.configHash,
+    listed: profile.listed,
+  };
+}
+
+/**
+ * Detect the lazy publish activation scenario.
+ *
+ * Decision matrix:
+ * - A: Not registered + has pending → first-time activation
+ * - B1: Registered + pending hash != on-chain hash + not listed → re-publish + list
+ * - B2: Registered + pending hash != on-chain hash + already listed → re-publish only
+ * - C: Pending hash == on-chain hash → stale pending, delete it
+ * - none: No pending publish file
+ */
+export function detectLazyPublishScenario(
+  onChainState: OnChainAgentState,
+  pendingPublish: PendingPublish | null
+): ActivationScenario {
+  if (!pendingPublish) return 'none';
+
+  const isRegistered = onChainState.registeredAt > 0n;
+  const pendingHash = pendingPublish.configHash;
+  const onChainHash = onChainState.configHash;
+
+  if (!isRegistered) {
+    // Not registered — scenario A: full activation
+    return 'A';
+  }
+
+  // Registered — check if pending hash differs from on-chain
+  if (pendingHash !== onChainHash) {
+    // Config differs — need to publish
+    return onChainState.listed ? 'B2' : 'B1';
+  }
+
+  // Hash matches — stale pending
+  return 'C';
 }
 
 function validateStateDirectory(stateDirectory: string): void {
@@ -519,6 +566,39 @@ export class ACTPClient {
    */
   private readonly walletProvider?: IWalletProvider;
 
+  /**
+   * Lazy Publish: Current activation scenario.
+   * Set during create(), consumed during first payACTPBatched().
+   * @internal
+   */
+  private lazyScenario: ActivationScenario = 'none';
+
+  /**
+   * Lazy Publish: Cached pending publish data.
+   * @internal
+   */
+  private pendingPublish: PendingPublish | null = null;
+
+  /**
+   * AgentRegistry address (for lazy activation calls).
+   * @internal
+   */
+  private agentRegistryAddress?: string;
+
+  /**
+   * Network identifier (e.g. 'base-sepolia', 'base-mainnet').
+   * Used for chain-scoped pending-publish file operations.
+   * @internal
+   */
+  private networkId?: string;
+
+  /**
+   * Whether the pending publish config is stale (AGIRAILS.md changed since last publish).
+   * When true, getActivationCalls() returns empty to prevent stale config going on-chain.
+   * @internal
+   */
+  private pendingIsStale = false;
+
   /**
    * Private constructor - use ACTPClient.create() factory method.
    */
@@ -530,14 +610,22 @@ export class ACTPClient {
     erc8004Bridge?: ERC8004Bridge,
     reputationReporter?: ReputationReporter,
     walletProvider?: IWalletProvider,
-    contractAddresses?: { usdc: string; actpKernel: string; escrowVault: string }
+    contractAddresses?: { usdc: string; actpKernel: string; escrowVault: string },
+    lazyScenario: ActivationScenario = 'none',
+    pendingPublish: PendingPublish | null = null,
+    agentRegistryAddress?: string,
+    networkId?: string,
   ) {
     this.runtime = runtime;
     this.info = info;
     this.easHelper = easHelper;
     this.reputationReporter = reputationReporter;
     this.walletProvider = walletProvider;
-    this.basic = new BasicAdapter(runtime, requesterAddress, easHelper, walletProvider, contractAddresses);
+    this.lazyScenario = lazyScenario;
+    this.pendingPublish = pendingPublish;
+    this.agentRegistryAddress = agentRegistryAddress;
+    this.networkId = networkId;
+    this.basic = new BasicAdapter(runtime, requesterAddress, easHelper, walletProvider, contractAddresses, this);
     this.standard = new StandardAdapter(runtime, requesterAddress, easHelper);
 
     // Initialize registry and router
@@ -594,6 +682,10 @@ export class ACTPClient {
     let walletProvider: IWalletProvider | undefined;
     let requesterAddress: string;
     let contractAddresses: { usdc: string; actpKernel: string; escrowVault: string } | undefined;
+    let lazyScenario: ActivationScenario = 'none';
+    let lazyPending: PendingPublish | null = null;
+    let registryAddr: string | undefined;
+    let networkId: string | undefined;
 
     // If custom runtime provided, use it directly
     if (config.runtime) {
@@ -613,17 +705,18 @@ export class ACTPClient {
       // Initialize runtime based on mode
       switch (config.mode) {
         case 'mock': {
-          // Mock mode: requesterAddress is mandatory
-          if (!config.requesterAddress) {
-            throw new Error('requesterAddress is required for mock mode');
-          }
-          if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
-            throw new Error(
-              `Invalid requesterAddress: "${config.requesterAddress}". ` +
-                'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)'
-            );
+          // Mock mode: requesterAddress is optional (auto-generate if missing)
+          if (config.requesterAddress) {
+            if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
+              throw new Error(
+                `Invalid requesterAddress: "${config.requesterAddress}". ` +
+                  'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)'
+              );
+            }
+            requesterAddress = config.requesterAddress;
+          } else {
+            requesterAddress = ethers.Wallet.createRandom().address;
           }
-          requesterAddress = config.requesterAddress;
 
           // SECURITY FIX: Enhanced path validation to prevent path traversal attacks
           if (config.stateDirectory) {
@@ -640,15 +733,27 @@ export class ACTPClient {
 
         case 'testnet':
         case 'mainnet': {
-          // Validate required parameters for blockchain modes
+          // Auto-detect private key from keystore / env var if not provided
           if (!config.privateKey) {
-            throw new Error(
-              `privateKey is required for ${config.mode} mode`
-            );
+            const { resolvePrivateKey } = await import('./wallet/keystore');
+            const resolved = await resolvePrivateKey(config.stateDirectory);
+            if (resolved) {
+              config = { ...config, privateKey: resolved };
+            } else {
+              throw new Error(
+                `No wallet found for ${config.mode} mode.\n\n` +
+                'Provide a private key via one of:\n' +
+                '  1. ACTP_KEY_PASSWORD env var + .actp/keystore.json (recommended)\n' +
+                '  2. ACTP_PRIVATE_KEY env var\n' +
+                '  3. privateKey option in ACTPClient.create()\n' +
+                '  4. Run "actp publish" to generate a wallet automatically'
+              );
+            }
           }
 
           // Map mode to network config
           const network = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+          networkId = network;
           const networkConfig = getNetwork(network);
 
           // Default RPC URL from network config if not provided
@@ -661,7 +766,8 @@ export class ACTPClient {
 
           // Create ethers provider and signer
           const provider = new ethers.JsonRpcProvider(rpcUrl);
-          const signer = new ethers.Wallet(config.privateKey, provider);
+          const privateKey = config.privateKey!; // Guaranteed by auto-detect above
+          const signer = new ethers.Wallet(privateKey, provider);
 
           // ====================================================================
           // AIP-12: Wallet Provider Selection
@@ -705,43 +811,72 @@ export class ACTPClient {
               },
             });
 
-            // Check AgentRegistry — gasless only for registered agents
+            // Check AgentRegistry + Lazy Publish scenario
             const smartWalletAddress = autoWallet.getAddress();
-            const agentRegistryAddress = config.contracts?.agentRegistry
+            registryAddr = config.contracts?.agentRegistry
               ?? networkConfig.contracts.agentRegistry;
 
-            let isRegistered = false;
-            if (agentRegistryAddress) {
+            // Load pending publish (may be null) — chain-scoped
+            try {
+              lazyPending = loadPendingPublish(network);
+            } catch {
+              // Ignore file read errors
+            }
+
+            let useAutoWallet = false;
+
+            if (registryAddr) {
               try {
-                isRegistered = await checkRegistration(
-                  provider, agentRegistryAddress, smartWalletAddress
+                const onChainState = await getOnChainAgentState(
+                  provider, registryAddr, smartWalletAddress
                 );
+                lazyScenario = detectLazyPublishScenario(onChainState, lazyPending);
+
+                // Scenario C: stale pending — delete immediately
+                if (lazyScenario === 'C') {
+                  deletePendingPublish(network);
+                  lazyPending = null;
+                  lazyScenario = 'none';
+                }
+
+                // Gate: configHash != ZERO || hasPendingPublish → use AutoWallet
+                const hasOnChainConfig = onChainState.configHash !== ZERO_HASH;
+                const hasPendingPublish = lazyPending !== null;
+
+                if (hasOnChainConfig || hasPendingPublish) {
+                  useAutoWallet = true;
+                }
               } catch {
-                // Registry check failed (e.g. RPC down) — allow AA anyway.
-                // Rationale: don't punish legit registered agents for infra issues.
-                // Paymaster contract allowlist + rate limits prevent abuse.
-                isRegistered = true;
-                sdkLogger.warn('AgentRegistry check failed, proceeding with AA wallet');
+                // Registry check failed (e.g. RPC down).
+                // Fail-open only if pending publish exists (agent did `actp publish` → legitimate intent).
+                // Fail-closed otherwise to prevent unregistered agents getting free gas.
+                if (lazyPending) {
+                  useAutoWallet = true;
+                  sdkLogger.warn('AgentRegistry check failed, but pending publish found — proceeding with AA.');
+                } else {
+                  sdkLogger.warn('AgentRegistry check failed and no pending publish — falling back to EOA.');
+                }
               }
             } else {
               // No registry deployed — skip check (early testnet)
-              isRegistered = true;
+              useAutoWallet = true;
             }
 
-            if (isRegistered) {
+            if (useAutoWallet) {
               walletProvider = autoWallet;
               requesterAddress = smartWalletAddress;
             } else {
-              // Not registered — fall back to EOA with warning
+              // Not published and no pending — fall back to EOA with warning
               sdkLogger.warn(
-                'Agent not registered on AgentRegistry. ' +
+                'Agent not published on AgentRegistry and no pending publish found. ' +
                 'Falling back to EOA wallet (gas not sponsored). ' +
-                'Run "actp register" for gas-free transactions.'
+                'Run "actp publish" for gas-free transactions.'
               );
               walletProvider = new EOAWalletProvider(signer, networkConfig.chainId);
-              // Force signer.address — config.requesterAddress may be the Smart Wallet
-              // address (set by `actp init --wallet auto`), which would be wrong for EOA.
               requesterAddress = signer.address;
+              // Reset since we're not using auto wallet
+              lazyScenario = 'none';
+              lazyPending = null;
             }
           } else {
             // Tier 2: EOA Wallet (backward compatible)
@@ -824,11 +959,35 @@ export class ACTPClient {
       walletTier: walletProvider?.getWalletInfo().tier,
     };
 
-    // Pass wallet provider and contract addresses to constructor
+    // Staleness check: recompute hash if AGIRAILS.md exists and we have a pending publish
+    let pendingIsStale = false;
+    if (lazyPending && lazyScenario !== 'none' && lazyScenario !== 'C') {
+      try {
+        const mdPath = path.join(process.cwd(), 'AGIRAILS.md');
+        if (fs.existsSync(mdPath)) {
+          const { computeConfigHash } = await import('./config/agirailsmd');
+          const content = fs.readFileSync(mdPath, 'utf-8');
+          const { configHash: currentHash } = computeConfigHash(content);
+          if (currentHash !== lazyPending.configHash) {
+            pendingIsStale = true;
+            sdkLogger.warn(
+              'AGIRAILS.md changed since last publish. Activation skipped. ' +
+              'Run "actp publish" to update.'
+            );
+          }
+        }
+      } catch {
+        // Best-effort: staleness check should not block operation
+      }
+    }
+
+    // Pass wallet provider, contract addresses, and lazy publish state to constructor
     const client = new ACTPClient(
       runtime, normalizedAddress, info, easHelper,
-      erc8004Bridge, reputationReporter, walletProvider, contractAddresses
+      erc8004Bridge, reputationReporter, walletProvider, contractAddresses,
+      lazyScenario, lazyPending, registryAddr, networkId,
     );
+    client.pendingIsStale = pendingIsStale;
 
     // Drift detection: non-blocking check for AGIRAILS.md sync status
     if (config.mode !== 'mock') {
@@ -1239,7 +1398,7 @@ export class ACTPClient {
    * @example
    * ```typescript
    * // Register a custom x402 adapter
-   * client.registerAdapter(new X402Adapter(client.runtime, requesterAddress));
+   * client.registerAdapter(new X402Adapter(requesterAddress, { expectedNetwork, transferFn }));
    * ```
    */
   registerAdapter(adapter: IAdapter): void {
@@ -1299,6 +1458,56 @@ export class ACTPClient {
     return this.walletProvider;
   }
 
+  /**
+   * Get activation calls for lazy publish.
+   *
+   * Returns SmartWalletCall[] to prepend to the first payment UserOp,
+   * plus an onSuccess callback that deletes pending-publish.json.
+   *
+   * Returns empty calls if no activation is needed (scenario C/none).
+   * @internal
+   */
+  getActivationCalls(): { calls: SmartWalletCall[]; onSuccess: () => void } {
+    if (this.lazyScenario === 'none' || this.lazyScenario === 'C' || !this.agentRegistryAddress) {
+      return { calls: [], onSuccess: () => {} };
+    }
+
+    // Staleness check: AGIRAILS.md changed since last publish → skip activation
+    if (this.pendingIsStale) {
+      return { calls: [], onSuccess: () => {} };
+    }
+
+    const pending = this.pendingPublish;
+    if (!pending) {
+      return { calls: [], onSuccess: () => {} };
+    }
+
+    // Build activation batch params
+    const params: import('./wallet/aa/TransactionBatcher').ActivationBatchParams = {
+      scenario: this.lazyScenario,
+      agentRegistryAddress: this.agentRegistryAddress,
+      cid: pending.cid,
+      configHash: pending.configHash,
+      listed: true,
+    };
+
+    // For scenario A, extract registration params from pending publish
+    if (this.lazyScenario === 'A') {
+      params.endpoint = pending.endpoint;
+      params.serviceDescriptors = pending.serviceDescriptors;
+    }
+
+    const calls = buildActivationBatch(params);
+
+    const onSuccess = () => {
+      deletePendingPublish(this.networkId);
+      this.lazyScenario = 'none';
+      this.pendingPublish = null;
+    };
+
+    return { calls, onSuccess };
+  }
+
   /**
    * Non-blocking drift detection for AGIRAILS.md config.
    * Checks if local AGIRAILS.md matches on-chain config hash.
@@ -1313,7 +1522,14 @@ export class ACTPClient {
       // Look for AGIRAILS.md in cwd
       const agirailsMdPath = join(process.cwd(), 'AGIRAILS.md');
       if (!existsSync(agirailsMdPath)) {
-        return; // No local file — nothing to check
+        // No local file — try cached hash from pending-publish.json
+        const { loadPendingPublish: loadPP } = await import('./config/pendingPublish');
+        const driftNetwork = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+        const pp = loadPP(driftNetwork);
+        if (pp) {
+          sdkLogger.info('[AGIRAILS] No AGIRAILS.md found, using cached config hash from pending-publish.json');
+        }
+        return;
       }
 
       const network = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';

package/src/adapters/BasicAdapter.ts

@@ -23,8 +23,17 @@ import {
   UnifiedPayResult,
 } from '../types/adapter';
 import { IWalletProvider } from '../wallet/IWalletProvider';
+import { SmartWalletCall } from '../wallet/aa/constants';
 import { ethers } from 'ethers';
 
+/**
+ * Interface for lazy publish activation call provider.
+ * ACTPClient implements this to avoid circular dependency.
+ */
+export interface IActivationCallProvider {
+  getActivationCalls(): { calls: SmartWalletCall[]; onSuccess: () => void };
+}
+
 /**
  * Parameters for creating a simple payment.
  *
@@ -126,7 +135,8 @@ export class BasicAdapter extends BaseAdapter implements IAdapter {
     requesterAddress: string,
     private easHelper?: EASHelper,
     private walletProvider?: IWalletProvider,
-    private contractAddresses?: { usdc: string; actpKernel: string; escrowVault: string }
+    private contractAddresses?: { usdc: string; actpKernel: string; escrowVault: string },
+    private activationProvider?: IActivationCallProvider,
   ) {
     super(requesterAddress);
   }
@@ -194,25 +204,51 @@ export class BasicAdapter extends BaseAdapter implements IAdapter {
     }
 
     // ====================================================================
-    // AIP-12: Batched payment via AA wallet (1 UserOp = 3 on-chain calls)
+    // AIP-12: Batched payment via AA wallet (1 UserOp = N on-chain calls)
+    // With lazy publish: activation calls prepended to first payment.
     // ====================================================================
     if (this.walletProvider?.payACTPBatched && this.contractAddresses) {
       const serviceHash = ethers.ZeroHash;
-      const result = await this.walletProvider.payACTPBatched({
-        provider,
-        requester,
-        amount: amount.toString(),
-        deadline,
-        disputeWindow,
-        serviceHash,
-        agentId: agentId || '0',
-        contracts: this.contractAddresses,
-      });
+
+      // Get lazy publish activation calls (if any)
+      let prependCalls: SmartWalletCall[] = [];
+      let onActivationSuccess: (() => void) | undefined;
+
+      if (this.activationProvider) {
+        const activation = this.activationProvider.getActivationCalls();
+        prependCalls = activation.calls;
+        if (prependCalls.length > 0) {
+          onActivationSuccess = activation.onSuccess;
+        }
+      }
+
+      const result = await this.walletProvider.payACTPBatched(
+        {
+          provider,
+          requester,
+          amount: amount.toString(),
+          deadline,
+          disputeWindow,
+          serviceHash,
+          agentId: agentId || '0',
+          contracts: this.contractAddresses,
+        },
+        prependCalls.length > 0 ? prependCalls : undefined,
+      );
 
       if (!result.success) {
         throw new Error(`Batched payment UserOp failed: ${result.hash}`);
       }
 
+      // Delete pending-publish.json on successful activation (best-effort)
+      if (onActivationSuccess) {
+        try {
+          onActivationSuccess();
+        } catch {
+          // Best-effort: activation succeeded, don't crash over cleanup
+        }
+      }
+
       return {
         txId: result.txId,
         provider,