@agirails/sdk 2.2.2 → 2.3.0

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,

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