@agirails/sdk 2.2.3 → 2.3.1

package/src/cli/commands/pull.ts

@@ -0,0 +1,124 @@
+/**
+ * Pull Command - Pull on-chain config to local AGIRAILS.md
+ *
+ * Fetches the published AGIRAILS.md from IPFS (via on-chain CID),
+ * verifies integrity against on-chain hash, and writes locally.
+ * Use --force to overwrite existing file without confirmation.
+ *
+ * @module cli/commands/pull
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { mapError } from '../utils/client';
+import { resolve } from 'path';
+import { ethers } from 'ethers';
+import { pull } from '../../config/syncOperations';
+import { getNetwork } from '../../config/networks';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createPullCommand(): Command {
+  const cmd = new Command('pull')
+    .description('Pull on-chain AGIRAILS.md config to local file')
+    .argument('[path]', 'Path to write AGIRAILS.md', './AGIRAILS.md')
+    .option('-n, --network <network>', 'Network (base-sepolia | base-mainnet)', 'base-sepolia')
+    .option('-a, --address <address>', 'Agent address to pull config for')
+    .option('--force', 'Overwrite without confirmation (CI mode)')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Minimal output')
+    .action(async (path, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runPull(path, options, output);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+interface PullCommandOptions {
+  network: string;
+  address?: string;
+  force?: boolean;
+}
+
+async function runPull(
+  filePath: string,
+  options: PullCommandOptions,
+  output: Output
+): Promise<void> {
+  const resolvedPath = resolve(filePath);
+
+  // Determine agent address
+  let agentAddress = options.address;
+  if (!agentAddress) {
+    const privateKey = process.env.ACTP_PRIVATE_KEY || process.env.PRIVATE_KEY;
+    if (!privateKey) {
+      output.error('Agent address required. Use --address or set ACTP_PRIVATE_KEY env var.');
+      process.exit(ExitCode.INVALID_INPUT);
+    }
+    agentAddress = new ethers.Wallet(privateKey).address;
+  }
+
+  const networkConfig = getNetwork(options.network);
+  if (!networkConfig.contracts.agentRegistry) {
+    output.error(`AgentRegistry not deployed on ${options.network}`);
+    process.exit(ExitCode.ERROR);
+  }
+
+  const spinner = output.spinner('Pulling config from on-chain...');
+
+  try {
+    const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
+
+    const result = await pull({
+      path: resolvedPath,
+      agentAddress,
+      registryAddress: networkConfig.contracts.agentRegistry,
+      provider,
+      force: options.force,
+    });
+
+    spinner.stop(result.written);
+
+    output.result(
+      {
+        written: result.written,
+        cid: result.cid || null,
+        status: result.status,
+        path: resolvedPath,
+        network: options.network,
+      },
+      { quietKey: 'status' }
+    );
+
+    if (result.written) {
+      output.blank();
+      output.success(`Config pulled and written to ${filePath}`);
+    } else {
+      output.blank();
+      output.info(result.status);
+    }
+  } catch (error) {
+    spinner.stop(false);
+    throw error;
+  }
+}

package/src/cli/commands/register.ts

@@ -0,0 +1,233 @@
+/**
+ * Register Command — Register agent on AgentRegistry for gas-free transactions.
+ *
+ * Parses AGIRAILS.md for service descriptors and endpoint, then registers
+ * on-chain via a single gasless UserOp (bootstrap-allowed).
+ *
+ * For testnet: also mints 1000 test USDC in the same UserOp.
+ *
+ * WARNING: This creates a NEW Smart Wallet address (different from EOA).
+ * Old EOA reputation/history does not transfer.
+ *
+ * @module cli/commands/register
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { loadConfig, updateConfig } from '../utils/config';
+import { resolvePrivateKey } from '../../wallet/keystore';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+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('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Minimal output')
+    .action(async (options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runRegister(options, output);
+      } catch (error) {
+        output.errorResult({
+          code: 'REGISTER_FAILED',
+          message: (error as Error).message,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+async function runRegister(
+  options: { endpoint?: string },
+  output: Output
+): Promise<void> {
+  const projectRoot = process.cwd();
+
+  // Load config
+  const config = loadConfig(projectRoot);
+  if (!config) {
+    throw new Error(
+      'ACTP not initialized. Run "actp init" first.'
+    );
+  }
+
+  if (config.mode === 'mock') {
+    throw new Error('Registration is not available in mock mode.');
+  }
+
+  // Resolve private key
+  const privateKey = await resolvePrivateKey(projectRoot);
+  if (!privateKey) {
+    throw new Error(
+      'No wallet found. Run "actp init" first to generate a wallet.'
+    );
+  }
+
+  // Parse AGIRAILS.md for service descriptors
+  const { parseAgirailsMd } = await import('../../config/agirailsmd');
+  const { extractRegistrationParams } = await import('../../config/publishPipeline');
+
+  const agirailsMdPath = path.join(projectRoot, 'AGIRAILS.md');
+  let endpoint = options.endpoint || '';
+  let serviceDescriptors;
+
+  if (fs.existsSync(agirailsMdPath)) {
+    const content = fs.readFileSync(agirailsMdPath, 'utf-8');
+    const parsed = parseAgirailsMd(content);
+    const regParams = extractRegistrationParams(parsed.frontmatter);
+    endpoint = options.endpoint || regParams.endpoint;
+    serviceDescriptors = regParams.serviceDescriptors;
+    output.info(`Parsed ${serviceDescriptors.length} service(s) from AGIRAILS.md`);
+  } else {
+    // No AGIRAILS.md — use minimal defaults
+    const { ethers: ethersLib } = await import('ethers');
+    const serviceType = 'general';
+    serviceDescriptors = [{
+      serviceTypeHash: ethersLib.keccak256(ethersLib.toUtf8Bytes(serviceType)),
+      serviceType,
+      schemaURI: '',
+      minPrice: 0n,
+      maxPrice: 1_000_000_000n, // 1000 USDC
+      avgCompletionTime: 3600,
+      metadataCID: '',
+    }];
+    output.warning('No AGIRAILS.md found. Using default "general" service descriptor.');
+    output.info('Create AGIRAILS.md with services to customize registration.');
+  }
+
+  // Dynamic imports
+  const { ethers } = await import('ethers');
+  const { getNetwork } = await import('../../config/networks');
+  const { AutoWalletProvider } = await import('../../wallet/AutoWalletProvider');
+  const { buildRegisterAgentBatch, buildTestnetInitBatch } = await import('../../wallet/aa/TransactionBatcher');
+
+  const network = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+  const networkConfig = getNetwork(network);
+
+  if (!networkConfig.aa) {
+    throw new Error(
+      `AA configuration not available for ${config.mode}. ` +
+      'Smart Wallet registration requires AA support.'
+    );
+  }
+
+  if (!networkConfig.contracts.agentRegistry) {
+    throw new Error(
+      'AgentRegistry contract not deployed yet. Registration not available.'
+    );
+  }
+
+  const rpcUrl = networkConfig.rpcUrl;
+  const provider = new ethers.JsonRpcProvider(rpcUrl);
+  const signer = new ethers.Wallet(privateKey, provider);
+
+  output.info('Creating Smart Wallet...');
+
+  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}`);
+
+  if (smartWalletAddress.toLowerCase() !== config.address.toLowerCase()) {
+    output.warning(
+      `This creates a NEW address: ${smartWalletAddress}\n` +
+      `  Your current address: ${config.address}\n` +
+      '  Old address reputation/history does NOT transfer.'
+    );
+  }
+
+  // Build batch — testnet gets register + mint, mainnet gets register only
+  let calls;
+  if (config.mode === 'testnet') {
+    output.info('Testnet mode: will register + mint 1000 test USDC in one UserOp');
+    calls = buildTestnetInitBatch({
+      agentRegistryAddress: networkConfig.contracts.agentRegistry,
+      endpoint,
+      serviceDescriptors,
+      mockUsdcAddress: networkConfig.contracts.usdc,
+      recipient: smartWalletAddress,
+      mintAmount: '1000000000', // 1000 USDC
+    });
+  } else {
+    calls = buildRegisterAgentBatch(
+      networkConfig.contracts.agentRegistry,
+      endpoint,
+      serviceDescriptors
+    );
+  }
+
+  // Convert SmartWalletCall[] to TransactionRequest[]
+  const txRequests = calls.map((c) => ({
+    to: c.target,
+    data: c.data,
+    value: c.value.toString(),
+  }));
+
+  output.info('Submitting registration (gasless UserOp)...');
+
+  const receipt = await autoWallet.sendBatchTransaction(txRequests);
+
+  if (!receipt.success) {
+    throw new Error(`Registration UserOp failed: ${receipt.hash}`);
+  }
+
+  output.success('Agent registered on AgentRegistry');
+  if (config.mode === 'testnet') {
+    output.success('Minted 1,000 test USDC to Smart Wallet');
+  }
+
+  // Update config: flip address to Smart Wallet, mark as registered
+  updateConfig({
+    address: smartWalletAddress.toLowerCase(),
+    smartWallet: smartWalletAddress.toLowerCase(),
+    registered: true,
+  }, projectRoot);
+  output.info('Config updated: address set to Smart Wallet');
+
+  output.blank();
+  output.result(
+    {
+      registered: true,
+      smartWallet: smartWalletAddress,
+      services: serviceDescriptors.length,
+      txHash: receipt.hash,
+      ...(config.mode === 'testnet' && { mintedUSDC: '1000' }),
+    },
+    { quietKey: 'smartWallet' }
+  );
+
+  output.blank();
+  output.print('Your agent now has gas-free transactions!');
+  output.print(`Smart Wallet address: ${smartWalletAddress}`);
+  output.print('');
+  output.print('To use gas-free mode, add to your agent config:');
+  output.print('  wallet: "auto"');
+}

package/src/cli/index.ts

@@ -48,6 +48,10 @@ import { createWatchCommand } from './commands/watch';
 import { createSimulateCommand } from './commands/simulate';
 import { createBatchCommand } from './commands/batch';
 import { createTimeCommand } from './commands/time';
+import { createPublishCommand } from './commands/publish';
+import { createPullCommand } from './commands/pull';
+import { createDiffCommand } from './commands/diff';
+import { createRegisterCommand } from './commands/register';
 
 // ============================================================================
 // Program Setup
@@ -92,6 +96,14 @@ program.addCommand(createBatchCommand());
 // Mock mode utilities
 program.addCommand(createTimeCommand());
 
+// Config sync commands (AGIRAILS.md as source of truth)
+program.addCommand(createPublishCommand());
+program.addCommand(createPullCommand());
+program.addCommand(createDiffCommand());
+
+// AIP-12: Gas-free registration
+program.addCommand(createRegisterCommand());
+
 // ============================================================================
 // Error Handling
 // ============================================================================

package/src/cli/utils/config.ts

@@ -35,6 +35,15 @@ export interface CLIConfig {
   /** Optional: RPC URL override */
   rpcUrl?: string;
 
+  /** 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`) */
+  smartWallet?: string;
+
+  /** AIP-12: Whether agent is registered on AgentRegistry */
+  registered?: boolean;
+
   /** Configuration version for migrations */
   version: string;
 }

package/src/config/agirailsmd.ts

@@ -0,0 +1,262 @@
+/**
+ * AGIRAILS.md Parser + Canonical Hash
+ *
+ * Parses AGIRAILS.md files (YAML frontmatter + markdown body),
+ * computes deterministic canonical hashes for on-chain verification.
+ *
+ * ## Canonical Hash Algorithm
+ *
+ * 1. Parse YAML frontmatter into a plain object
+ * 2. **Strip publish metadata keys** (config_hash, published_at, config_cid, arweave_tx)
+ *    — these are written back by the publish pipeline and must not affect the hash
+ * 3. Canonicalize frontmatter:
+ *    - Object keys: sorted lexicographically (recursive)
+ *    - Primitive arrays: sorted lexicographically by `String(value).localeCompare()`
+ *    - Object arrays: order preserved (semantic ordering matters)
+ *    - Date objects: converted to ISO-8601 string (`.toISOString()`)
+ *    - null/undefined: preserved as-is
+ * 4. `structuredHash = keccak256(JSON.stringify(canonical))`
+ * 5. Normalize body: CRLF→LF, strip trailing whitespace per line, trim
+ * 6. `bodyHash = keccak256(normalizedBody)`
+ * 7. `configHash = keccak256(structuredHash ++ bodyHash)` (byte concatenation)
+ *
+ * @module config/agirailsmd
+ */
+
+import { ethers } from 'ethers';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AgirailsMdConfig {
+  /** Parsed YAML frontmatter as a plain object */
+  frontmatter: Record<string, unknown>;
+  /** Markdown body (everything after the closing ---) */
+  body: string;
+}
+
+export interface AgirailsMdHashResult {
+  /** Final configHash = keccak256(structuredHash + bodyHash) */
+  configHash: string;
+  /** Hash of the canonical JSON representation of frontmatter */
+  structuredHash: string;
+  /** Hash of the normalized markdown body */
+  bodyHash: string;
+}
+
+// ============================================================================
+// Publish Metadata (excluded from hash computation)
+// ============================================================================
+
+/**
+ * Frontmatter keys written by the publish pipeline.
+ * These are stripped before hash computation to prevent self-reference drift:
+ * publish writes config_hash back → changes frontmatter → changes hash → never in sync.
+ */
+export const PUBLISH_METADATA_KEYS = [
+  'config_hash',
+  'published_at',
+  'config_cid',
+  'arweave_tx',
+  'template_source',
+] as const;
+
+/**
+ * Strip publish metadata keys from a frontmatter object.
+ * Returns a shallow copy with the metadata keys removed.
+ */
+export function stripPublishMetadata(
+  frontmatter: Record<string, unknown>
+): Record<string, unknown> {
+  const stripped = { ...frontmatter };
+  for (const key of PUBLISH_METADATA_KEYS) {
+    delete stripped[key];
+  }
+  return stripped;
+}
+
+// ============================================================================
+// Parser
+// ============================================================================
+
+/**
+ * Parse an AGIRAILS.md file into frontmatter + body.
+ *
+ * @param content - Raw file content (string)
+ * @returns Parsed config with frontmatter object and body string
+ * @throws Error if content has no valid YAML frontmatter
+ */
+export function parseAgirailsMd(content: string): AgirailsMdConfig {
+  const trimmed = content.trimStart();
+
+  if (!trimmed.startsWith('---')) {
+    throw new Error('AGIRAILS.md must start with YAML frontmatter (---)');
+  }
+
+  // Find closing ---
+  const closingIndex = trimmed.indexOf('\n---', 3);
+  if (closingIndex === -1) {
+    throw new Error('AGIRAILS.md frontmatter is not closed (missing closing ---)');
+  }
+
+  const yamlContent = trimmed.slice(4, closingIndex); // skip opening ---\n
+  const body = trimmed.slice(closingIndex + 4); // skip \n---
+
+  // Parse YAML
+  let frontmatter: Record<string, unknown>;
+  try {
+    frontmatter = parseYaml(yamlContent);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to parse YAML frontmatter: ${message}`);
+  }
+
+  if (typeof frontmatter !== 'object' || frontmatter === null) {
+    throw new Error('YAML frontmatter must be an object');
+  }
+
+  return {
+    frontmatter,
+    body: body.startsWith('\n') ? body.slice(1) : body,
+  };
+}
+
+// ============================================================================
+// Canonical Hash
+// ============================================================================
+
+/**
+ * Recursively canonicalize a value for deterministic JSON serialization.
+ *
+ * - Object keys: sorted lexicographically
+ * - Primitive arrays: sorted by String(x).localeCompare()
+ * - Object arrays: order preserved
+ * - Date objects: converted to ISO-8601 string
+ * - null/undefined: preserved
+ */
+export function canonicalize(value: unknown): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  // Handle Date objects deterministically (YAML parser may auto-create these)
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  if (Array.isArray(value)) {
+    // Canonicalize each element, then sort arrays of primitives lexicographically
+    const canonicalized = value.map(canonicalize);
+
+    // Only sort arrays of primitives (strings, numbers, booleans)
+    // Arrays of objects maintain order (e.g., onboarding questions have semantic ordering)
+    const allPrimitive = canonicalized.every(
+      (item) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean'
+    );
+
+    if (allPrimitive) {
+      return canonicalized.sort((a, b) => String(a).localeCompare(String(b)));
+    }
+
+    return canonicalized;
+  }
+
+  if (typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    for (const key of keys) {
+      sorted[key] = canonicalize((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+
+  return value;
+}
+
+/**
+ * Normalize markdown body for deterministic hashing.
+ * - Strip trailing whitespace from each line
+ * - Ensure \n line endings
+ * - Trim leading/trailing whitespace
+ */
+function normalizeBody(body: string): string {
+  return body
+    .replace(/\r\n/g, '\n') // CRLF → LF
+    .replace(/\r/g, '\n') // CR → LF
+    .split('\n')
+    .map((line) => line.trimEnd()) // strip trailing whitespace per line
+    .join('\n')
+    .trim(); // trim leading/trailing
+}
+
+/**
+ * Compute the canonical config hash from raw AGIRAILS.md content.
+ *
+ * @param content - Raw AGIRAILS.md file content
+ * @returns Hash result with configHash, structuredHash, and bodyHash
+ */
+export function computeConfigHash(content: string): AgirailsMdHashResult {
+  const { frontmatter, body } = parseAgirailsMd(content);
+  return computeConfigHashFromParts(frontmatter, body);
+}
+
+/**
+ * Compute the canonical config hash from parsed parts.
+ *
+ * Publish metadata keys (config_hash, published_at, config_cid, arweave_tx)
+ * are automatically stripped before hashing to prevent self-reference drift.
+ *
+ * @param frontmatter - Parsed YAML frontmatter object
+ * @param body - Markdown body string
+ * @returns Hash result with configHash, structuredHash, and bodyHash
+ */
+export function computeConfigHashFromParts(
+  frontmatter: Record<string, unknown>,
+  body: string
+): AgirailsMdHashResult {
+  // Step 0: Strip publish metadata to prevent self-reference drift
+  const stripped = stripPublishMetadata(frontmatter);
+
+  // Step 1: Canonical JSON of frontmatter (with metadata stripped)
+  const canonical = canonicalize(stripped);
+  const canonicalJson = JSON.stringify(canonical);
+  const structuredHash = ethers.keccak256(ethers.toUtf8Bytes(canonicalJson));
+
+  // Step 2: Normalized body hash
+  const normalized = normalizeBody(body);
+  const bodyHash = ethers.keccak256(ethers.toUtf8Bytes(normalized));
+
+  // Step 3: Combined hash
+  const configHash = ethers.keccak256(
+    ethers.concat([ethers.getBytes(structuredHash), ethers.getBytes(bodyHash)])
+  );
+
+  return { configHash, structuredHash, bodyHash };
+}
+
+// ============================================================================
+// Serializer
+// ============================================================================
+
+/**
+ * Serialize config back to AGIRAILS.md format.
+ *
+ * @param frontmatter - YAML frontmatter object
+ * @param body - Markdown body string
+ * @returns Complete AGIRAILS.md file content
+ */
+export function serializeAgirailsMd(
+  frontmatter: Record<string, unknown>,
+  body: string
+): string {
+  const yamlStr = stringifyYaml(frontmatter, {
+    lineWidth: 120,
+    singleQuote: false,
+  }).trimEnd();
+
+  const normalizedBody = body.startsWith('\n') ? body : `\n${body}`;
+
+  return `---\n${yamlStr}\n---\n${normalizedBody}`;
+}