@agirails/sdk 2.2.3 → 2.3.0

package/src/cli/commands/publish.ts

@@ -0,0 +1,209 @@
+/**
+ * Publish Command - Publish AGIRAILS.md config on-chain
+ *
+ * Reads AGIRAILS.md, computes canonical hash, uploads to IPFS,
+ * optionally to Arweave, and records on AgentRegistry.
+ *
+ * @module cli/commands/publish
+ */
+
+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, serializeAgirailsMd } from '../../config/agirailsmd';
+import { AgentRegistryClient } from '../../registry/AgentRegistryClient';
+import { FilebaseClient } from '../../storage/FilebaseClient';
+import { ArweaveClient } from '../../storage/ArweaveClient';
+import { getNetwork } from '../../config/networks';
+import { publishAgirailsMd, PENDING_ENDPOINT } from '../../config/publishPipeline';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createPublishCommand(): Command {
+  const cmd = new Command('publish')
+    .description('Publish AGIRAILS.md config on-chain')
+    .argument('[path]', 'Path to AGIRAILS.md', './AGIRAILS.md')
+    .option('-n, --network <network>', 'Network (base-sepolia | base-mainnet)', 'base-sepolia')
+    .option('--skip-arweave', 'Skip permanent Arweave storage (dev mode)')
+    .option('--dry-run', 'Show what would happen without executing')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only the config hash')
+    .action(async (path, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runPublish(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 PublishCommandOptions {
+  network: string;
+  skipArweave?: boolean;
+  dryRun?: boolean;
+}
+
+async function runPublish(
+  filePath: string,
+  options: PublishCommandOptions,
+  output: Output
+): Promise<void> {
+  const resolvedPath = resolve(filePath);
+
+  if (!existsSync(resolvedPath)) {
+    output.error(`File not found: ${filePath}`);
+    process.exit(ExitCode.INVALID_INPUT);
+  }
+
+  const spinner = output.spinner('Reading AGIRAILS.md...');
+
+  try {
+    // Read and compute hash
+    const content = readFileSync(resolvedPath, 'utf-8');
+    const { configHash, structuredHash, bodyHash } = computeConfigHash(content);
+
+    if (options.dryRun) {
+      spinner.stop(true);
+
+      output.result(
+        {
+          configHash,
+          structuredHash,
+          bodyHash,
+          path: resolvedPath,
+          network: options.network,
+          dryRun: true,
+        },
+        { quietKey: 'configHash' }
+      );
+
+      output.blank();
+      output.success('Dry run complete. No changes made.');
+      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);
+    }
+
+    const networkConfig = getNetwork(options.network);
+    if (!networkConfig.contracts.agentRegistry) {
+      spinner.stop(false);
+      output.error(`AgentRegistry not deployed on ${options.network}`);
+      process.exit(ExitCode.ERROR);
+    }
+
+    // Create provider and signer
+    const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
+    const signer = new ethers.Wallet(privateKey, provider);
+
+    // Create Filebase client
+    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 filebaseClient = new FilebaseClient({
+      accessKey: filebaseAccessKey,
+      secretKey: filebaseSecretKey,
+    });
+
+    // 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,
+        });
+      }
+    }
+
+    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,
+      },
+    });
+
+    publishSpinner.stop(true);
+
+    output.result(
+      {
+        configHash: result.configHash,
+        cid: result.cid,
+        txHash: result.txHash,
+        arweaveTxId: result.arweaveTxId || null,
+        registered: result.registered || false,
+        network: options.network,
+      },
+      { quietKey: 'configHash' }
+    );
+
+    output.blank();
+    if (result.registered) {
+      output.success('Agent registered and config published!');
+    } else {
+      output.success('Config published successfully!');
+    }
+    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');
+      }
+    }
+  } catch (error) {
+    spinner.stop(false);
+    throw error;
+  }
+}

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/index.ts

@@ -48,6 +48,9 @@ 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';
 
 // ============================================================================
 // Program Setup
@@ -92,6 +95,11 @@ 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());
+
 // ============================================================================
 // Error Handling
 // ============================================================================

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}`;
+}

package/src/config/networks.ts

@@ -32,9 +32,11 @@ export interface NetworkConfig {
     agentRegistry?: string; // AIP-7 Agent Registry (optional until deployed)
     identityRegistry?: string; // AIP-7 ERC-1056 DID Registry (optional until deployed)
     archiveTreasury?: string; // AIP-7 Archive Treasury for Arweave funding (optional until deployed)
+    x402Relay?: string; // X402Relay for atomic payment fee splitting (optional until deployed)
   };
   eas: {
     deliverySchemaUID: string; // AIP-4 delivery proof schema
+    configSnapshotSchemaUID?: string; // AGIRAILS.md config snapshot schema
   };
   gasSettings: {
     maxFeePerGas: bigint;
@@ -70,7 +72,9 @@ export const BASE_SEPOLIA: NetworkConfig = {
     // AIP-7 Identity Registry - ERC-1056 DID Registry (deployed 2026-01-09)
     identityRegistry: '0xF64F748C7802a68Cb936a9213881fE74e83FDA97',
     // AIP-7 Archive Treasury - Arweave funding (deployed 2026-01-09)
-    archiveTreasury: '0xeB75DE7cF5ce77ab15BB0fFa3a2A79e6aaa554B0'
+    archiveTreasury: '0xeB75DE7cF5ce77ab15BB0fFa3a2A79e6aaa554B0',
+    // X402Relay - atomic payment fee splitting (TODO: deploy and set address)
+    // x402Relay: '0x...',
   },
   eas: {
     // Deployed 2025-11-23 - AIP-4 delivery proof schema
@@ -104,7 +108,9 @@ export const BASE_MAINNET: NetworkConfig = {
     easSchemaRegistry: '0x4200000000000000000000000000000000000020',
     // AIP-7 contracts
     agentRegistry: '0xbf9Aa0FC291A06A4dFA943c3E0Ad41E7aE20DF02',
-    archiveTreasury: '0x64B8f93fef2D2E749F5E88586753343F73246012'
+    archiveTreasury: '0x64B8f93fef2D2E749F5E88586753343F73246012',
+    // X402Relay - atomic payment fee splitting (TODO: deploy and set address)
+    // x402Relay: '0x...',
   },
   eas: {
     // Registered 2026-02-03
@@ -158,10 +164,12 @@ export function getNetwork(network: string): NetworkConfig {
       easSchemaRegistry: config.contracts.easSchemaRegistry,
       agentRegistry: config.contracts.agentRegistry,
       identityRegistry: config.contracts.identityRegistry,
-      archiveTreasury: config.contracts.archiveTreasury
+      archiveTreasury: config.contracts.archiveTreasury,
+      x402Relay: config.contracts.x402Relay
     },
     eas: {
-      deliverySchemaUID: config.eas.deliverySchemaUID
+      deliverySchemaUID: config.eas.deliverySchemaUID,
+      configSnapshotSchemaUID: config.eas.configSnapshotSchemaUID
     },
     gasSettings: {
       maxFeePerGas: config.gasSettings.maxFeePerGas,