@agirails/sdk 2.3.1 → 2.4.0

package/src/cli/utils/wallet.ts

@@ -0,0 +1,109 @@
+/**
+ * Wallet Utilities — Shared wallet generation and Smart Wallet derivation.
+ *
+ * Extracted from init.ts for reuse by both `actp init` and `actp publish`.
+ *
+ * @module cli/utils/wallet
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { Output } from './output';
+
+/**
+ * Generate a new encrypted wallet keystore.
+ *
+ * - Creates a random ethers.Wallet
+ * - Encrypts with password (from ACTP_KEY_PASSWORD env or interactive prompt)
+ * - Saves to `{actpDir}/keystore.json` with 0o600 permissions
+ *
+ * @param actpDir - Path to .actp directory
+ * @param output - CLI output handler
+ * @returns The generated wallet's address
+ */
+export async function generateWallet(actpDir: string, output: Output): Promise<string> {
+  const { Wallet } = await import('ethers');
+
+  const wallet = Wallet.createRandom();
+
+  // Get password from env var or interactive prompt
+  let password = process.env.ACTP_KEY_PASSWORD;
+  if (!password) {
+    password = await promptPassword();
+  }
+
+  if (!password || password.length < 8) {
+    throw new Error(
+      'Wallet password required (minimum 8 characters).\n' +
+        'Set ACTP_KEY_PASSWORD env var or enter when prompted.'
+    );
+  }
+
+  // Encrypt with Keystore V3 (scrypt + AES-128-CTR)
+  output.info('Encrypting wallet (this takes a few seconds)...');
+  const keystore = await wallet.encrypt(password);
+
+  // Save with restrictive permissions
+  const keystorePath = path.join(actpDir, 'keystore.json');
+  fs.writeFileSync(keystorePath, keystore, { mode: 0o600 });
+
+  output.success('Key securely saved and encrypted');
+  output.info(`Address: ${wallet.address}`);
+  output.warning('Back up your password — it cannot be recovered.');
+
+  return wallet.address;
+}
+
+/**
+ * Compute the Smart Wallet address for an EOA signer.
+ * Uses CREATE2 counterfactual derivation — no deployment needed.
+ *
+ * @param eoaAddress - The EOA signer address
+ * @param mode - 'testnet' or 'mainnet'
+ * @param output - CLI output handler
+ * @returns The derived Smart Wallet address
+ */
+export async function computeSmartWalletInit(
+  eoaAddress: string,
+  mode: string,
+  output: Output
+): Promise<string> {
+  const { ethers } = await import('ethers');
+  const { getNetwork } = await import('../../config/networks');
+  const { computeSmartWalletAddress } = await import('../../wallet/aa/UserOpBuilder');
+
+  const network = mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+  const networkConfig = getNetwork(network);
+  const rpcUrl = networkConfig.rpcUrl;
+  const provider = new ethers.JsonRpcProvider(rpcUrl);
+
+  output.info('Computing Smart Wallet address...');
+  const smartWalletAddress = await computeSmartWalletAddress(eoaAddress, provider);
+
+  output.success(`Smart Wallet: ${smartWalletAddress}`);
+
+  return smartWalletAddress;
+}
+
+/**
+ * Interactive password prompt (TTY only).
+ * Returns empty string in non-TTY environments (piped/agent mode).
+ */
+async function promptPassword(): Promise<string> {
+  if (!process.stdin.isTTY) {
+    return '';
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question('Enter password for wallet encryption (min 8 chars): ', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}

package/src/config/pendingPublish.ts

@@ -0,0 +1,226 @@
+/**
+ * Pending Publish Module — Deferred on-chain activation for Lazy Publish.
+ *
+ * When `actp publish` runs, it saves a `pending-publish.{network}.json` file
+ * instead of making on-chain calls. The first real payment triggers activation
+ * (registerAgent, publishConfig, setListed) in a single UserOp alongside the
+ * payment calls.
+ *
+ * Files are chain-scoped: testnet and mainnet pending publishes coexist independently.
+ * Legacy `pending-publish.json` (unscoped) is supported for migration.
+ *
+ * The file is deleted after successful on-chain activation.
+ *
+ * @module config/pendingPublish
+ */
+
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { ServiceDescriptor } from '../types/agent';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Serializable representation of a ServiceDescriptor.
+ * BigInt fields are stored as strings for JSON compatibility.
+ */
+interface SerializedServiceDescriptor {
+  serviceTypeHash: string;
+  serviceType: string;
+  schemaURI: string;
+  minPrice: string;
+  maxPrice: string;
+  avgCompletionTime: number;
+  metadataCID: string;
+}
+
+/**
+ * Pending publish state — saved to `.actp/pending-publish.{network}.json`.
+ */
+export interface PendingPublish {
+  /** Schema version */
+  version: 1;
+  /** Canonical config hash (bytes32) */
+  configHash: string;
+  /** IPFS CID of uploaded AGIRAILS.md */
+  cid: string;
+  /** Agent endpoint URL */
+  endpoint: string;
+  /** Service descriptors from AGIRAILS.md frontmatter */
+  serviceDescriptors: ServiceDescriptor[];
+  /** ISO 8601 timestamp of when pending-publish.json was created */
+  createdAt: string;
+  /** Network identifier (e.g. 'base-sepolia', 'base-mainnet') */
+  network?: string;
+}
+
+/**
+ * JSON-serializable form of PendingPublish (bigints as strings).
+ */
+interface SerializedPendingPublish {
+  version: 1;
+  configHash: string;
+  cid: string;
+  endpoint: string;
+  serviceDescriptors: SerializedServiceDescriptor[];
+  createdAt: string;
+  network?: string;
+}
+
+// ============================================================================
+// Serialization Helpers
+// ============================================================================
+
+function serializeDescriptor(sd: ServiceDescriptor): SerializedServiceDescriptor {
+  return {
+    serviceTypeHash: sd.serviceTypeHash,
+    serviceType: sd.serviceType,
+    schemaURI: sd.schemaURI,
+    minPrice: sd.minPrice.toString(),
+    maxPrice: sd.maxPrice.toString(),
+    avgCompletionTime: sd.avgCompletionTime,
+    metadataCID: sd.metadataCID,
+  };
+}
+
+function deserializeDescriptor(sd: SerializedServiceDescriptor): ServiceDescriptor {
+  return {
+    serviceTypeHash: sd.serviceTypeHash,
+    serviceType: sd.serviceType,
+    schemaURI: sd.schemaURI,
+    minPrice: BigInt(sd.minPrice),
+    maxPrice: BigInt(sd.maxPrice),
+    avgCompletionTime: sd.avgCompletionTime,
+    metadataCID: sd.metadataCID,
+  };
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Get the .actp directory path.
+ *
+ * Respects `ACTP_DIR` env var for custom locations.
+ * Defaults to `{cwd}/.actp`.
+ */
+export function getActpDir(): string {
+  return process.env.ACTP_DIR || join(process.cwd(), '.actp');
+}
+
+/**
+ * Get the path to a pending-publish file.
+ *
+ * @param network - Optional network identifier. If provided, returns
+ *   `pending-publish.{network}.json`. Otherwise returns legacy `pending-publish.json`.
+ */
+export function getPendingPublishPath(network?: string): string {
+  if (network) {
+    return join(getActpDir(), `pending-publish.${network}.json`);
+  }
+  return join(getActpDir(), 'pending-publish.json');
+}
+
+/**
+ * Save a pending publish to `.actp/pending-publish.{network}.json`.
+ *
+ * Creates the .actp directory if it doesn't exist.
+ * File is written atomically with mode 0o600 (owner read/write only).
+ *
+ * If `pending.network` is set, saves to network-scoped file.
+ * Otherwise saves to legacy `pending-publish.json`.
+ */
+export function savePendingPublish(pending: PendingPublish): void {
+  const dir = getActpDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const serialized: SerializedPendingPublish = {
+    version: pending.version,
+    configHash: pending.configHash,
+    cid: pending.cid,
+    endpoint: pending.endpoint,
+    serviceDescriptors: pending.serviceDescriptors.map(serializeDescriptor),
+    createdAt: pending.createdAt,
+    ...(pending.network ? { network: pending.network } : {}),
+  };
+
+  const filePath = getPendingPublishPath(pending.network);
+  writeFileSync(filePath, JSON.stringify(serialized, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Load a pending publish from `.actp/pending-publish.{network}.json`.
+ *
+ * If `network` is provided:
+ *   1. Try `pending-publish.{network}.json`
+ *   2. Fall back to legacy `pending-publish.json` (migration)
+ *
+ * If no `network`: loads legacy `pending-publish.json`.
+ *
+ * Returns null if no file found.
+ */
+export function loadPendingPublish(network?: string): PendingPublish | null {
+  // Try network-scoped file first
+  if (network) {
+    const scopedPath = getPendingPublishPath(network);
+    if (existsSync(scopedPath)) {
+      return deserializePendingPublish(readFileSync(scopedPath, 'utf-8'));
+    }
+  }
+
+  // Fall back to legacy file
+  const legacyPath = getPendingPublishPath();
+  if (!existsSync(legacyPath)) {
+    return null;
+  }
+
+  return deserializePendingPublish(readFileSync(legacyPath, 'utf-8'));
+}
+
+/**
+ * Delete the pending-publish file for a given network.
+ *
+ * Deletes both the network-scoped file and legacy file (cleanup).
+ * No-op if files don't exist. Best-effort — never throws.
+ */
+export function deletePendingPublish(network?: string): void {
+  try {
+    // Delete network-scoped file
+    if (network) {
+      const scopedPath = getPendingPublishPath(network);
+      if (existsSync(scopedPath)) {
+        unlinkSync(scopedPath);
+      }
+    }
+
+    // Also delete legacy file if it exists (cleanup)
+    const legacyPath = getPendingPublishPath();
+    if (existsSync(legacyPath)) {
+      unlinkSync(legacyPath);
+    }
+  } catch {
+    // Best-effort: file deletion should never crash post-payment UX
+  }
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function deserializePendingPublish(raw: string): PendingPublish {
+  const serialized: SerializedPendingPublish = JSON.parse(raw);
+  return {
+    version: serialized.version,
+    configHash: serialized.configHash,
+    cid: serialized.cid,
+    endpoint: serialized.endpoint,
+    serviceDescriptors: serialized.serviceDescriptors.map(deserializeDescriptor),
+    createdAt: serialized.createdAt,
+    ...(serialized.network ? { network: serialized.network } : {}),
+  };
+}

package/src/config/publishPipeline.ts

@@ -176,7 +176,88 @@ export function extractRegistrationParams(
 }
 
 // ============================================================================
-// Pipeline
+// Prepare Publish (offline — no on-chain calls)
+// ============================================================================
+
+export interface PreparePublishOptions {
+  /** Path to AGIRAILS.md file */
+  path: string;
+  /** Filebase client for IPFS upload */
+  filebaseClient: FilebaseClient;
+  /** Arweave client for permanent storage (optional) */
+  arweaveClient?: ArweaveClient;
+  /** Skip Arweave upload */
+  skipArweave?: boolean;
+  /** Dry run — compute and show but don't execute */
+  dryRun?: boolean;
+}
+
+export interface PreparePublishResult {
+  /** IPFS CID of uploaded AGIRAILS.md */
+  cid: string;
+  /** Canonical config hash (bytes32) */
+  configHash: string;
+  /** Arweave transaction ID (if uploaded) */
+  arweaveTxId?: string;
+  /** Parsed frontmatter */
+  frontmatter: Record<string, unknown>;
+  /** Parsed body */
+  body: string;
+  /** Whether this was a dry run */
+  dryRun: boolean;
+}
+
+/**
+ * Prepare publish — IPFS upload + hash computation only.
+ *
+ * No on-chain calls. Returns the CID and configHash for
+ * saving to pending-publish.json (lazy publish flow).
+ */
+export async function preparePublish(options: PreparePublishOptions): Promise<PreparePublishResult> {
+  const {
+    path,
+    filebaseClient,
+    arweaveClient,
+    skipArweave = false,
+    dryRun = false,
+  } = options;
+
+  // Read and parse
+  const content = readFileSync(path, 'utf-8');
+  const { frontmatter, body } = parseAgirailsMd(content);
+  const { configHash } = computeConfigHash(content);
+
+  if (dryRun) {
+    return { cid: '(dry-run)', configHash, frontmatter, body, dryRun: true };
+  }
+
+  // Upload to IPFS
+  const ipfsResult = await filebaseClient.uploadBinary(
+    Buffer.from(content, 'utf-8'),
+    'text/markdown',
+    { metadata: { type: 'agirails-config', version: '1.0' } }
+  );
+  const cid = ipfsResult.cid;
+
+  // Arweave (optional)
+  let arweaveTxId: string | undefined;
+  if (!skipArweave && arweaveClient) {
+    const arweaveResult = await arweaveClient.uploadJSON(
+      { frontmatter, body, _format: 'agirails.md.v1' },
+      [
+        { name: 'Type', value: 'agent-config' },
+        { name: 'ConfigHash', value: configHash },
+        { name: 'IPFS-CID', value: cid },
+      ]
+    );
+    arweaveTxId = arweaveResult.txId;
+  }
+
+  return { cid, configHash, arweaveTxId, frontmatter, body, dryRun: false };
+}
+
+// ============================================================================
+// Pipeline (legacy — makes on-chain calls)
 // ============================================================================
 
 /**

package/src/index.ts

@@ -64,6 +64,12 @@ export {
   StandardTransactionParams,
 } from './adapters/StandardAdapter';
 
+export {
+  X402Adapter,
+  X402AdapterConfig,
+  X402PayParams,
+} from './adapters/X402Adapter';
+
 export { AdapterRegistry } from './adapters/AdapterRegistry';
 
 export {
@@ -353,4 +359,6 @@ export {
   ArweaveTimeoutError,
   InvalidArweaveTxIdError,
   InsufficientBalanceError as StorageInsufficientBalanceError,
+  SwapExecutionError,
+  QueryCapExceededError,
 } from './errors';

package/src/wallet/AutoWalletProvider.ts

@@ -191,7 +191,7 @@ export class AutoWalletProvider implements IWalletProvider {
    * Builds approve + createTransaction + linkEscrow as a single UserOp.
    * Manages ACTP nonce inside the mutex queue for concurrent safety.
    */
-  async payACTPBatched(params: BatchedPayParams): Promise<BatchedPayResult> {
+  async payACTPBatched(params: BatchedPayParams, prependCalls?: SmartWalletCall[]): Promise<BatchedPayResult> {
     return this.nonceManager.enqueue(
       async ({ entryPointNonce, actpNonce }) => {
         const batch = buildACTPPayBatch({
@@ -199,7 +199,12 @@ export class AutoWalletProvider implements IWalletProvider {
           actpNonce,
         });
 
-        const receipt = await this.submitUserOp(batch.calls, entryPointNonce);
+        // Combine activation calls (if any) with payment calls
+        const allCalls = prependCalls && prependCalls.length > 0
+          ? [...prependCalls, ...batch.calls]
+          : batch.calls;
+
+        const receipt = await this.submitUserOp(allCalls, entryPointNonce);
 
         return {
           result: {

package/src/wallet/IWalletProvider.ts

@@ -127,7 +127,9 @@ export interface IWalletProvider {
    * Only available on AA wallets (supportsBatching: true).
    * Handles ACTP nonce management internally via the DualNonceManager mutex.
    *
-   * Returns undefined if batched payments are not supported.
+   * @param params - Payment batch parameters
+   * @param prependCalls - Optional calls to prepend (e.g., lazy publish activation)
+   * @returns undefined if batched payments are not supported.
    */
-  payACTPBatched?(params: BatchedPayParams): Promise<BatchedPayResult>;
+  payACTPBatched?(params: BatchedPayParams, prependCalls?: import('./aa/constants').SmartWalletCall[]): Promise<BatchedPayResult>;
 }

package/src/wallet/aa/BundlerClient.ts

@@ -233,8 +233,9 @@ export class BundlerClient {
       const json = (await response.json()) as JsonRpcResponse<T>;
 
       if (json.error) {
+        const dataStr = json.error.data ? ` | data: ${JSON.stringify(json.error.data)}` : '';
         const err = new Error(
-          `Bundler RPC error ${json.error.code}: ${json.error.message}`
+          `Bundler RPC error ${json.error.code}: ${json.error.message}${dataStr}`
         );
         (err as any).code = json.error.code;
         (err as any).data = json.error.data;

package/src/wallet/aa/DualNonceManager.ts

@@ -141,17 +141,27 @@ export class DualNonceManager {
 
   /**
    * Read current ACTP nonce for the requester.
-   * requesterNonces is public on ACTPKernel.
+   * requesterNonces is public on ACTPKernel (added in v2).
+   * Older deployments may not expose this — fall back to 0n.
    */
   private async readActpNonce(): Promise<bigint> {
-    const kernel = new ethers.Contract(
-      this.actpKernelAddress,
-      ACTP_KERNEL_NONCE_ABI,
-      this.provider
-    );
-    const nonce = await kernel.requesterNonces(this.senderAddress);
-    this.cachedActpNonce = nonce;
-    return nonce;
+    try {
+      const kernel = new ethers.Contract(
+        this.actpKernelAddress,
+        ACTP_KERNEL_NONCE_ABI,
+        this.provider
+      );
+      const nonce = await kernel.requesterNonces(this.senderAddress);
+      this.cachedActpNonce = nonce;
+      return nonce;
+    } catch {
+      // Older ACTPKernel deployments don't expose requesterNonces.
+      // Return 0n — registration doesn't need it, and payment batches
+      // will fail at the contract level anyway if nonces are wrong.
+      sdkLogger.warn('requesterNonces not available on ACTPKernel — using 0 (older deployment?)');
+      this.cachedActpNonce = 0n;
+      return 0n;
+    }
   }
 
   /**

package/src/wallet/aa/PaymasterClient.ts

@@ -160,8 +160,9 @@ export class PaymasterClient {
       const json = (await response.json()) as JsonRpcResponse<T>;
 
       if (json.error) {
+        const dataStr = json.error.data ? ` | data: ${JSON.stringify(json.error.data)}` : '';
         throw new Error(
-          `Paymaster RPC error ${json.error.code}: ${json.error.message}`
+          `Paymaster RPC error ${json.error.code}: ${json.error.message}${dataStr}`
         );
       }
 

package/src/wallet/aa/TransactionBatcher.ts

@@ -154,6 +154,8 @@ export function buildACTPPayBatch(params: ACTPBatchParams): ACTPBatchResult {
  */
 const AGENT_REGISTRY_ABI = [
   'function registerAgent(string endpoint, (bytes32 serviceTypeHash, string serviceType, string schemaURI, uint256 minPrice, uint256 maxPrice, uint256 avgCompletionTime, string metadataCID)[] serviceDescriptors)',
+  'function publishConfig(string cid, bytes32 configHash)',
+  'function setListed(bool listed)',
 ];
 
 /**
@@ -238,3 +240,114 @@ export function buildTestnetInitBatch(params: {
   );
   return [...registerCalls, ...mintCalls];
 }
+
+// ============================================================================
+// Lazy Publish — Activation Batch Builders
+// ============================================================================
+
+/**
+ * Lazy publish activation scenario.
+ *
+ * - 'A': First activation — registerAgent + publishConfig + setListed (3 calls)
+ * - 'B1': Re-publish with listing change — publishConfig + setListed (2 calls)
+ * - 'B2': Re-publish config only — publishConfig (1 call)
+ * - 'C': Stale pending — delete pending-publish.json, no calls
+ * - 'none': No pending publish, normal flow
+ */
+export type ActivationScenario = 'A' | 'B1' | 'B2' | 'C' | 'none';
+
+/**
+ * Parameters for building an activation batch.
+ */
+export interface ActivationBatchParams {
+  /** Activation scenario */
+  scenario: ActivationScenario;
+  /** AgentRegistry contract address */
+  agentRegistryAddress: string;
+  /** IPFS CID of the published AGIRAILS.md */
+  cid: string;
+  /** Canonical config hash (bytes32) */
+  configHash: string;
+  /** Agent endpoint URL (for scenario A registration) */
+  endpoint?: string;
+  /** Service descriptors (for scenario A registration) */
+  serviceDescriptors?: ServiceDescriptor[];
+  /** Whether to set listed=true (for scenarios A, B1) */
+  listed?: boolean;
+}
+
+/**
+ * Build a publishConfig batch call for AgentRegistry.
+ *
+ * @param agentRegistryAddress - AgentRegistry contract address
+ * @param cid - IPFS CID of the uploaded AGIRAILS.md
+ * @param configHash - Canonical config hash (bytes32)
+ */
+export function buildPublishConfigBatch(
+  agentRegistryAddress: string,
+  cid: string,
+  configHash: string
+): SmartWalletCall[] {
+  const iface = new ethers.Interface(AGENT_REGISTRY_ABI);
+  const data = iface.encodeFunctionData('publishConfig', [cid, configHash]);
+  return [{ target: agentRegistryAddress, value: 0n, data }];
+}
+
+/**
+ * Build a setListed batch call for AgentRegistry.
+ *
+ * @param agentRegistryAddress - AgentRegistry contract address
+ * @param listed - Whether to list the agent
+ */
+export function buildSetListedBatch(
+  agentRegistryAddress: string,
+  listed: boolean
+): SmartWalletCall[] {
+  const iface = new ethers.Interface(AGENT_REGISTRY_ABI);
+  const data = iface.encodeFunctionData('setListed', [listed]);
+  return [{ target: agentRegistryAddress, value: 0n, data }];
+}
+
+/**
+ * Build the full activation batch based on scenario.
+ *
+ * Scenario call counts:
+ * - A: registerAgent + publishConfig + setListed = 3 calls
+ * - B1: publishConfig + setListed = 2 calls
+ * - B2: publishConfig = 1 call
+ * - C/none: empty (0 calls)
+ */
+export function buildActivationBatch(params: ActivationBatchParams): SmartWalletCall[] {
+  const { scenario, agentRegistryAddress, cid, configHash } = params;
+
+  switch (scenario) {
+    case 'A': {
+      // First activation: register + publish + list
+      if (!params.endpoint || !params.serviceDescriptors || params.serviceDescriptors.length === 0) {
+        throw new Error('Scenario A requires endpoint and serviceDescriptors');
+      }
+      const registerCalls = buildRegisterAgentBatch(
+        agentRegistryAddress,
+        params.endpoint,
+        params.serviceDescriptors
+      );
+      const publishCalls = buildPublishConfigBatch(agentRegistryAddress, cid, configHash);
+      const listCalls = buildSetListedBatch(agentRegistryAddress, params.listed ?? true);
+      return [...registerCalls, ...publishCalls, ...listCalls];
+    }
+    case 'B1': {
+      // Re-publish with listing: publish + list
+      const publishCalls = buildPublishConfigBatch(agentRegistryAddress, cid, configHash);
+      const listCalls = buildSetListedBatch(agentRegistryAddress, params.listed ?? true);
+      return [...publishCalls, ...listCalls];
+    }
+    case 'B2': {
+      // Re-publish config only
+      return buildPublishConfigBatch(agentRegistryAddress, cid, configHash);
+    }
+    case 'C':
+    case 'none':
+      // Stale or no pending — no activation calls
+      return [];
+  }
+}