@agirails/sdk 2.2.3 → 2.3.0

package/src/config/publishPipeline.ts

@@ -0,0 +1,276 @@
+/**
+ * Publish Pipeline - AGIRAILS.md → IPFS → Arweave → On-Chain
+ *
+ * Orchestrates the full publish flow:
+ * 1. Read AGIRAILS.md → parse → compute configHash
+ * 2. Upload to Filebase (IPFS pinning)
+ * 3. Upload to Arweave (permanent storage) [optional]
+ * 4. Call AgentRegistry.publishConfig(cid, hash) on-chain
+ * 5. Update AGIRAILS.md frontmatter with config_hash and published_at
+ *
+ * @module config/publishPipeline
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { Signer, keccak256, toUtf8Bytes } from 'ethers';
+import { parseAgirailsMd, computeConfigHash, computeConfigHashFromParts, serializeAgirailsMd } from './agirailsmd';
+import { AgentRegistryClient } from '../registry/AgentRegistryClient';
+import { AgentRegistry } from '../protocol/AgentRegistry';
+import { FilebaseClient } from '../storage/FilebaseClient';
+import { ArweaveClient } from '../storage/ArweaveClient';
+import { ServiceDescriptor } from '../types';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PublishOptions {
+  /** Path to AGIRAILS.md file */
+  path: string;
+  /** Network name (for registry address lookup) */
+  network: string;
+  /** AgentRegistry contract address */
+  registryAddress: string;
+  /** Signer for on-chain transactions */
+  signer: Signer;
+  /** Filebase client for IPFS upload */
+  filebaseClient: FilebaseClient;
+  /** Arweave client for permanent storage (optional) */
+  arweaveClient?: ArweaveClient;
+  /** Skip Arweave upload (dev mode) */
+  skipArweave?: boolean;
+  /** Dry run - compute and show but don't execute */
+  dryRun?: boolean;
+  /** Gas settings */
+  gasSettings?: {
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+  };
+}
+
+export interface PublishResult {
+  /** IPFS CID of the uploaded AGIRAILS.md */
+  cid: string;
+  /** Canonical config hash (bytes32) */
+  configHash: string;
+  /** On-chain transaction hash */
+  txHash?: string;
+  /** Arweave transaction ID (if uploaded) */
+  arweaveTxId?: string;
+  /** Whether this was a dry run */
+  dryRun: boolean;
+  /** Whether the agent was auto-registered during this publish */
+  registered?: boolean;
+}
+
+// ============================================================================
+// Registration Helpers
+// ============================================================================
+
+export const PENDING_ENDPOINT = 'https://pending.agirails.io';
+
+/** Default values for capabilities-to-services conversion */
+const SERVICE_DEFAULTS = {
+  schemaURI: '',
+  minPrice: 0n,
+  maxPrice: 1_000_000_000n, // 1000 USDC
+  avgCompletionTime: 3600,  // 1 hour
+  metadataCID: '',
+};
+
+/** Max safe USDC value before BigInt conversion loses precision */
+const MAX_SAFE_USDC = Math.floor(Number.MAX_SAFE_INTEGER / 1_000_000);
+
+/** Validate service type format (must match contract requirements) */
+function validateServiceType(serviceType: string, source: string): void {
+  if (!serviceType) {
+    throw new Error(`Empty service type in ${source}`);
+  }
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(serviceType)) {
+    throw new Error(
+      `Invalid service type "${serviceType}" in ${source}. ` +
+      'Must be lowercase alphanumeric with hyphens (e.g., "text-generation").'
+    );
+  }
+}
+
+/** Convert human-readable USDC to 6-decimal base units with overflow check */
+function usdcToBaseUnits(value: number, fieldName: string): bigint {
+  if (value < 0) throw new Error(`${fieldName} cannot be negative`);
+  if (value > MAX_SAFE_USDC) throw new Error(`${fieldName} exceeds maximum safe value (${MAX_SAFE_USDC} USDC)`);
+  return BigInt(Math.round(value * 1_000_000));
+}
+
+/**
+ * Extract registration params from AGIRAILS.md frontmatter.
+ *
+ * Supports two formats:
+ * - `services`: full ServiceDescriptor objects with pricing
+ * - `capabilities`: simple string list, auto-converted with defaults
+ *
+ * @throws Error if neither services nor capabilities are present
+ */
+function extractRegistrationParams(
+  frontmatter: Record<string, unknown>
+): { endpoint: string; serviceDescriptors: ServiceDescriptor[] } {
+  // Endpoint: use frontmatter field or placeholder
+  const endpoint = typeof frontmatter.endpoint === 'string' && frontmatter.endpoint
+    ? frontmatter.endpoint
+    : PENDING_ENDPOINT;
+
+  // Try explicit services first
+  if (Array.isArray(frontmatter.services) && frontmatter.services.length > 0) {
+    const serviceDescriptors = (frontmatter.services as Record<string, unknown>[]).map(svc => {
+      const serviceType = String(svc.type || svc.service_type || '').trim().toLowerCase();
+      validateServiceType(serviceType, 'services');
+
+      // Parse price range: "1.0-100.0" or separate min/max
+      let minPrice = SERVICE_DEFAULTS.minPrice;
+      let maxPrice = SERVICE_DEFAULTS.maxPrice;
+      if (typeof svc.price === 'string' && svc.price.includes('-')) {
+        const [min, max] = svc.price.split('-').map(Number);
+        minPrice = usdcToBaseUnits(min, 'min_price');
+        maxPrice = usdcToBaseUnits(max, 'max_price');
+      } else {
+        if (svc.min_price !== undefined) minPrice = usdcToBaseUnits(Number(svc.min_price), 'min_price');
+        if (svc.max_price !== undefined) maxPrice = usdcToBaseUnits(Number(svc.max_price), 'max_price');
+      }
+
+      return {
+        serviceTypeHash: keccak256(toUtf8Bytes(serviceType)),
+        serviceType,
+        schemaURI: String(svc.schema_uri || svc.schemaURI || SERVICE_DEFAULTS.schemaURI),
+        minPrice,
+        maxPrice,
+        avgCompletionTime: Number(svc.avg_completion_time || svc.avgCompletionTime || SERVICE_DEFAULTS.avgCompletionTime),
+        metadataCID: String(svc.metadata_cid || svc.metadataCID || SERVICE_DEFAULTS.metadataCID),
+      };
+    });
+    return { endpoint, serviceDescriptors };
+  }
+
+  // Fallback: convert capabilities list to services with defaults
+  if (Array.isArray(frontmatter.capabilities) && frontmatter.capabilities.length > 0) {
+    const serviceDescriptors = (frontmatter.capabilities as string[]).map(cap => {
+      const serviceType = String(cap).trim().toLowerCase();
+      validateServiceType(serviceType, 'capabilities');
+      return {
+        serviceTypeHash: keccak256(toUtf8Bytes(serviceType)),
+        serviceType,
+        schemaURI: SERVICE_DEFAULTS.schemaURI,
+        minPrice: SERVICE_DEFAULTS.minPrice,
+        maxPrice: SERVICE_DEFAULTS.maxPrice,
+        avgCompletionTime: SERVICE_DEFAULTS.avgCompletionTime,
+        metadataCID: SERVICE_DEFAULTS.metadataCID,
+      };
+    });
+    return { endpoint, serviceDescriptors };
+  }
+
+  throw new Error(
+    'AGIRAILS.md must have "services" or "capabilities" in frontmatter for agent registration.\n' +
+    'Add at least one, e.g.:\n' +
+    '  capabilities:\n' +
+    '    - text-generation\n'
+  );
+}
+
+// ============================================================================
+// Pipeline
+// ============================================================================
+
+/**
+ * Execute the full publish pipeline.
+ *
+ * @param options - Publish configuration
+ * @returns Publish result with CID, hash, and transaction hashes
+ */
+export async function publishAgirailsMd(options: PublishOptions): Promise<PublishResult> {
+  const {
+    path,
+    registryAddress,
+    signer,
+    filebaseClient,
+    arweaveClient,
+    skipArweave = false,
+    dryRun = false,
+    gasSettings,
+  } = options;
+
+  // Step 1: 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,
+      dryRun: true,
+      registered: false,
+    };
+  }
+
+  // Step 2: Upload raw AGIRAILS.md to IPFS via Filebase
+  // Upload the actual markdown file (not a JSON wrapper) so CID points to the real file
+  const ipfsResult = await filebaseClient.uploadBinary(
+    Buffer.from(content, 'utf-8'),
+    'text/markdown',
+    { metadata: { type: 'agirails-config', version: '1.0' } }
+  );
+  const cid = ipfsResult.cid;
+
+  // Step 3: Upload to Arweave (optional)
+  // Arweave stores the JSON-structured form for archival querying.
+  // uploadJSON already sets Content-Type: application/json and Protocol: AGIRAILS as defaults.
+  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;
+  }
+
+  // Step 4: Auto-register if needed, then publish on-chain
+  const registry = new AgentRegistry(registryAddress, signer, gasSettings);
+  const registryClient = new AgentRegistryClient(registryAddress, signer, gasSettings);
+  let registered = false;
+
+  const signerAddress = await signer.getAddress();
+  const profile = await registry.getAgent(signerAddress);
+
+  if (!profile) {
+    // Not registered — extract params from frontmatter and auto-register
+    const regParams = extractRegistrationParams(frontmatter);
+    await registry.registerAgent(regParams);
+    registered = true;
+  }
+
+  const { txHash } = await registryClient.publishConfig(cid, configHash);
+
+  // Step 5: Update frontmatter with publish metadata
+  const updatedFrontmatter = {
+    ...frontmatter,
+    config_hash: configHash,
+    published_at: new Date().toISOString(),
+    config_cid: cid,
+    ...(arweaveTxId ? { arweave_tx: arweaveTxId } : {}),
+  };
+
+  const updatedContent = serializeAgirailsMd(updatedFrontmatter, body);
+  writeFileSync(path, updatedContent, 'utf-8');
+
+  return {
+    cid,
+    configHash,
+    txHash,
+    arweaveTxId,
+    dryRun: false,
+    registered,
+  };
+}

package/src/config/syncOperations.ts

@@ -0,0 +1,279 @@
+/**
+ * Sync Operations - Pull + Diff for AGIRAILS.md
+ *
+ * Terraform-style sync: compare local AGIRAILS.md with on-chain state.
+ * Never auto-overwrites — shows diff and requires explicit confirmation.
+ *
+ * @module config/syncOperations
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { Provider } from 'ethers';
+import { computeConfigHash, parseAgirailsMd, serializeAgirailsMd } from './agirailsmd';
+import { validateCID } from '../utils/validation';
+import { AgentRegistryClient } from '../registry/AgentRegistryClient';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Public IPFS gateways for read-only access (no credentials needed) */
+const IPFS_GATEWAYS = [
+  'https://ipfs.io/ipfs/',
+  'https://dweb.link/ipfs/',
+  'https://cloudflare-ipfs.com/ipfs/',
+];
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface DiffResult {
+  /** Whether local and on-chain are in sync */
+  inSync: boolean;
+  /** Local config hash (or null if no local file) */
+  localHash: string | null;
+  /** On-chain config hash (or zero hash if not published) */
+  onChainHash: string;
+  /** On-chain IPFS CID (or empty if not published) */
+  onChainCID: string;
+  /** Whether on-chain has a published config */
+  hasOnChainConfig: boolean;
+  /** Whether local file exists */
+  hasLocalFile: boolean;
+  /** Human-readable status message */
+  status: 'in-sync' | 'local-ahead' | 'remote-ahead' | 'diverged' | 'no-local' | 'no-remote';
+}
+
+export interface PullResult {
+  /** Whether a file was written */
+  written: boolean;
+  /** The pulled content (if any) */
+  content?: string;
+  /** IPFS CID that was fetched */
+  cid?: string;
+  /** Status message */
+  status: string;
+}
+
+export interface DiffOptions {
+  /** Path to local AGIRAILS.md */
+  path: string;
+  /** Agent address to check on-chain */
+  agentAddress: string;
+  /** AgentRegistry contract address */
+  registryAddress: string;
+  /** Provider for reading on-chain state */
+  provider: Provider;
+}
+
+export interface PullOptions extends DiffOptions {
+  /** Force overwrite without confirmation */
+  force?: boolean;
+}
+
+// ============================================================================
+// Diff
+// ============================================================================
+
+const ZERO_HASH = '0x' + '0'.repeat(64);
+
+/**
+ * Compare local AGIRAILS.md with on-chain config state.
+ *
+ * @param options - Diff configuration
+ * @returns Diff result showing sync status
+ */
+export async function diff(options: DiffOptions): Promise<DiffResult> {
+  const { path, agentAddress, registryAddress, provider } = options;
+
+  // Read on-chain state
+  const registryClient = AgentRegistryClient.readOnly(registryAddress, provider);
+  const onChainState = await registryClient.getConfig(agentAddress);
+
+  const hasOnChainConfig = onChainState.configHash !== ZERO_HASH && onChainState.configCID !== '';
+  const onChainHash = onChainState.configHash;
+  const onChainCID = onChainState.configCID;
+
+  // Read local state
+  const hasLocalFile = existsSync(path);
+  let localHash: string | null = null;
+
+  if (hasLocalFile) {
+    const content = readFileSync(path, 'utf-8');
+    const { configHash } = computeConfigHash(content);
+    localHash = configHash;
+  }
+
+  // Determine status
+  let status: DiffResult['status'];
+  let inSync: boolean;
+
+  if (!hasLocalFile && !hasOnChainConfig) {
+    status = 'no-local';
+    inSync = true; // both empty = in sync
+  } else if (!hasLocalFile && hasOnChainConfig) {
+    status = 'remote-ahead';
+    inSync = false;
+  } else if (hasLocalFile && !hasOnChainConfig) {
+    status = 'no-remote';
+    inSync = false;
+  } else if (localHash === onChainHash) {
+    status = 'in-sync';
+    inSync = true;
+  } else {
+    // Both exist but hashes differ. Use the stored config_hash in frontmatter
+    // to determine directionality:
+    // - config_hash matches on-chain → user edited locally after last publish → local-ahead
+    // - config_hash doesn't match on-chain → remote was updated too → diverged
+    // - no config_hash → never published from this file → local-ahead
+    status = 'diverged';
+    inSync = false;
+
+    if (hasLocalFile) {
+      try {
+        const content = readFileSync(path, 'utf-8');
+        const { frontmatter } = parseAgirailsMd(content);
+        if (!frontmatter.config_hash) {
+          // Never published — local is the only source
+          status = 'local-ahead';
+        } else if (frontmatter.config_hash === onChainHash) {
+          // Last publish matches on-chain, so local edits are newer
+          status = 'local-ahead';
+        }
+        // else: frontmatter.config_hash !== onChainHash → remote updated → diverged
+      } catch {
+        // Parse error — keep as diverged
+      }
+    }
+  }
+
+  return {
+    inSync,
+    localHash,
+    onChainHash,
+    onChainCID,
+    hasOnChainConfig,
+    hasLocalFile,
+    status,
+  };
+}
+
+// ============================================================================
+// IPFS Fetch (public gateway, no credentials needed)
+// ============================================================================
+
+/**
+ * Fetch content from IPFS using public gateways (no Filebase credentials needed).
+ * Tries multiple gateways with fallback.
+ *
+ * @param cid - IPFS CID to fetch (validated before use)
+ * @returns Raw content as string
+ * @throws InvalidCIDError if CID format is invalid
+ * @throws Error if all gateways fail
+ */
+async function fetchFromIPFS(cid: string): Promise<string> {
+  // Validate CID format before hitting any gateway
+  validateCID(cid, 'onChainCID');
+
+  const errors: string[] = [];
+
+  for (const gateway of IPFS_GATEWAYS) {
+    try {
+      const response = await fetch(`${gateway}${cid}`, {
+        signal: AbortSignal.timeout(15_000),
+      });
+      if (!response.ok) {
+        errors.push(`${gateway}: HTTP ${response.status}`);
+        continue;
+      }
+      return await response.text();
+    } catch (err) {
+      errors.push(`${gateway}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  throw new Error(
+    `Failed to fetch CID ${cid} from all IPFS gateways:\n${errors.map(e => `  - ${e}`).join('\n')}`
+  );
+}
+
+// ============================================================================
+// Pull
+// ============================================================================
+
+/**
+ * Pull on-chain config to local AGIRAILS.md.
+ *
+ * Downloads from IPFS via public gateways (no Filebase credentials needed),
+ * verifies integrity against on-chain configHash, then writes locally.
+ *
+ * @param options - Pull configuration
+ * @returns Pull result
+ */
+export async function pull(options: PullOptions): Promise<PullResult> {
+  const { path, agentAddress, registryAddress, provider, force = false } = options;
+
+  // First, run diff
+  const diffResult = await diff({ path, agentAddress, registryAddress, provider });
+
+  if (!diffResult.hasOnChainConfig) {
+    return {
+      written: false,
+      status: 'No config published on-chain for this agent.',
+    };
+  }
+
+  if (diffResult.inSync) {
+    return {
+      written: false,
+      status: 'Already in sync. No changes needed.',
+    };
+  }
+
+  // Fetch raw AGIRAILS.md from IPFS (public gateway, no credentials)
+  const content = await fetchFromIPFS(diffResult.onChainCID);
+
+  // Integrity verification: hash downloaded content and compare with on-chain hash
+  const { configHash: downloadedHash } = computeConfigHash(content);
+  if (downloadedHash !== diffResult.onChainHash) {
+    return {
+      written: false,
+      cid: diffResult.onChainCID,
+      status: `Integrity check failed! Downloaded content hash (${downloadedHash}) does not match on-chain hash (${diffResult.onChainHash}). The IPFS content may have been tampered with.`,
+    };
+  }
+
+  // Check if local file exists and we're not forcing
+  if (diffResult.hasLocalFile && !force) {
+    return {
+      written: false,
+      content,
+      cid: diffResult.onChainCID,
+      status: `Remote config differs from local. Use --force to overwrite. CID: ${diffResult.onChainCID}`,
+    };
+  }
+
+  // Stamp on-chain metadata into frontmatter so diff heuristic can detect
+  // future remote changes (without this, pulled files have no config_hash
+  // and diff would always report "local-ahead" instead of "diverged")
+  const { frontmatter, body } = parseAgirailsMd(content);
+  const stamped = serializeAgirailsMd(
+    {
+      ...frontmatter,
+      config_hash: diffResult.onChainHash,
+      config_cid: diffResult.onChainCID,
+    },
+    body
+  );
+
+  // Write the stamped file
+  writeFileSync(path, stamped, 'utf-8');
+
+  return {
+    written: true,
+    content: stamped,
+    cid: diffResult.onChainCID,
+    status: `Pulled and verified config from IPFS (${diffResult.onChainCID}) → ${path}`,
+  };
+}

package/src/index.ts

@@ -176,6 +176,9 @@ export {
   createUsedAttestationTracker,
 } from './utils/UsedAttestationTracker';
 
+// Wallet
+export { resolvePrivateKey, getCachedAddress } from './wallet/keystore';
+
 // Helper utilities
 export {
   USDC,