@agirails/sdk 2.5.3 → 2.5.4

package/src/config/agirailsmd.ts

@@ -1,262 +0,0 @@
-/**
- * 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

@@ -1,275 +0,0 @@
-import { ethers } from 'ethers';
-
-// ============================================================================
-// SECURITY FIX (C-7): RPC URL Configuration
-// ============================================================================
-// Environment variables take priority over hardcoded defaults.
-// This prevents accidental API key leakage if developers modify this file.
-// Public RPC endpoints are used as fallbacks for ease of use.
-//
-// Set these environment variables to use your own RPC provider:
-//   BASE_SEPOLIA_RPC - Custom RPC for Base Sepolia testnet
-//   BASE_MAINNET_RPC - Custom RPC for Base Mainnet
-// ============================================================================
-
-const BASE_SEPOLIA_RPC_URL = process.env.BASE_SEPOLIA_RPC || 'https://sepolia.base.org';
-const BASE_MAINNET_RPC_URL = process.env.BASE_MAINNET_RPC || 'https://mainnet.base.org';
-
-// AGIRAILS CDP Client API Key — safe to embed, cannot access funds/portfolios.
-// Developers can override with their own key via CDP_API_KEY env var.
-// Paymaster policy restricts sponsorship to AGIRAILS contracts only.
-const CDP_CLIENT_KEY = process.env.CDP_API_KEY || '2txciN85t41erCjveqgNnXYyHRcoo5xP';
-
-// Pimlico failover — bundler/paymaster backup if Coinbase CDP is down.
-// Safe to embed: restricted by contract allowlist (AGIRAILS contracts only).
-// Developers can override with their own key via PIMLICO_API_KEY env var.
-const PIMLICO_KEY = process.env.PIMLICO_API_KEY || 'pim_YiHmeAijzTPUvo1UMmXUiN';
-
-/**
- * Network configuration
- */
-export interface NetworkConfig {
-  name: string;
-  chainId: number;
-  rpcUrl: string;
-  blockExplorer: string;
-  contracts: {
-    actpKernel: string;
-    escrowVault: string;
-    usdc: string;
-    eas: string; // EAS contract address
-    easSchemaRegistry: string; // EAS SchemaRegistry contract
-    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;
-    maxPriorityFeePerGas: bigint;
-  };
-  /**
-   * Maximum transaction amount in USDC (human-readable, e.g., 100 = $100)
-   *
-   * SECURITY: Limits exposure on unaudited mainnet contracts.
-   * Set to undefined for no limit (testnet only).
-   */
-  maxTransactionAmount?: number;
-
-  /**
-   * AIP-12: Account Abstraction (AA) configuration.
-   * EntryPoint v0.6 + CoinbaseSmartWallet.
-   */
-  aa?: {
-    /** ERC-4337 EntryPoint v0.6 address */
-    entryPoint: string;
-    /** CoinbaseSmartWallet factory address */
-    smartWalletFactory: string;
-    /** Bundler RPC URLs */
-    bundlerUrls: {
-      coinbase: string;
-      pimlico?: string;
-    };
-    /** Paymaster RPC URLs (ERC-7677) */
-    paymasterUrls: {
-      coinbase: string;
-      pimlico?: string;
-    };
-  };
-}
-
-/**
- * Base Sepolia Testnet Configuration
- */
-export const BASE_SEPOLIA: NetworkConfig = {
-  name: 'Base Sepolia',
-  chainId: 84532,
-  rpcUrl: BASE_SEPOLIA_RPC_URL,
-  blockExplorer: 'https://sepolia.basescan.org',
-  contracts: {
-    actpKernel: '0x469CBADbACFFE096270594F0a31f0EEC53753411',
-    escrowVault: '0x57f888261b629bB380dfb983f5DA6c70Ff2D49E5',
-    usdc: '0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb', // MockUSDC
-    eas: '0x4200000000000000000000000000000000000021',
-    easSchemaRegistry: '0x4200000000000000000000000000000000000020',
-    agentRegistry: '0xDd6D66924B43419F484aE981F174b803487AF25A',
-    identityRegistry: '0xF64F748C7802a68Cb936a9213881fE74e83FDA97',
-    archiveTreasury: '0xeB75DE7cF5ce77ab15BB0fFa3a2A79e6aaa554B0',
-    x402Relay: '0x4DCD02b276Dbeab57c265B72435e90507b6Ac81A',
-  },
-  eas: {
-    deliverySchemaUID: '0x1b0ebdf0bd20c28ec9d5362571ce8715a55f46e81c3de2f9b0d8e1b95fb5ffce'
-  },
-  gasSettings: {
-    maxFeePerGas: ethers.parseUnits('2', 'gwei'),
-    maxPriorityFeePerGas: ethers.parseUnits('1', 'gwei')
-  },
-  // AIP-12: Account Abstraction
-  aa: {
-    entryPoint: '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789',
-    smartWalletFactory: '0xBA5ED110eFDBa3D005bfC882d75358ACBbB85842',
-    bundlerUrls: {
-      // Coinbase CDP bundler — set CDP_API_KEY env var
-      coinbase: process.env.CDP_BUNDLER_URL || `https://api.developer.coinbase.com/rpc/v1/base-sepolia/${CDP_CLIENT_KEY}`,
-      // Pimlico backup bundler — set PIMLICO_API_KEY env var
-      pimlico: process.env.PIMLICO_BUNDLER_URL || `https://api.pimlico.io/v2/84532/rpc?apikey=${PIMLICO_KEY}`,
-    },
-    paymasterUrls: {
-      // Coinbase CDP paymaster — same endpoint as bundler
-      coinbase: process.env.CDP_PAYMASTER_URL || `https://api.developer.coinbase.com/rpc/v1/base-sepolia/${CDP_CLIENT_KEY}`,
-      // Pimlico failover paymaster
-      pimlico: process.env.PIMLICO_PAYMASTER_URL || `https://api.pimlico.io/v2/84532/rpc?apikey=${PIMLICO_KEY}`,
-    },
-  },
-};
-
-/**
- * Base Mainnet Configuration
- */
-export const BASE_MAINNET: NetworkConfig = {
-  name: 'Base Mainnet',
-  chainId: 8453,
-  rpcUrl: BASE_MAINNET_RPC_URL,
-  blockExplorer: 'https://basescan.org',
-  contracts: {
-    actpKernel: '0x132B9eB321dBB57c828B083844287171BDC92d29',
-    escrowVault: '0x6aAF45882c4b0dD34130ecC790bb5Ec6be7fFb99',
-    usdc: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
-    eas: '0x4200000000000000000000000000000000000021',
-    easSchemaRegistry: '0x4200000000000000000000000000000000000020',
-    agentRegistry: '0x6fB222CF3DDdf37Bcb248EE7BBBA42Fb41901de8',
-    archiveTreasury: '0x0516C411C0E8d75D17A768022819a0a4FB3cA2f2',
-    x402Relay: '0x81DFb954A3D58FEc24Fc9c946aC2C71a911609F8',
-  },
-  eas: {
-    deliverySchemaUID: '0x166501e7476e2fcf9214c4c5144533c2957d56fe59d639effc1719a0658d9c9a'
-  },
-  gasSettings: {
-    maxFeePerGas: ethers.parseUnits('0.5', 'gwei'),
-    maxPriorityFeePerGas: ethers.parseUnits('0.1', 'gwei')
-  },
-  /**
-   * SECURITY: $1,000 max transaction limit until contracts are audited.
-   * This limits exposure in case of undiscovered vulnerabilities.
-   * Will be removed/increased after formal security audit.
-   */
-  maxTransactionAmount: 1000,
-  // AIP-12: Account Abstraction
-  aa: {
-    entryPoint: '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789',
-    smartWalletFactory: '0xBA5ED110eFDBa3D005bfC882d75358ACBbB85842',
-    bundlerUrls: {
-      coinbase: process.env.CDP_BUNDLER_URL || `https://api.developer.coinbase.com/rpc/v1/base/${CDP_CLIENT_KEY}`,
-      // Pimlico backup bundler — set PIMLICO_API_KEY env var
-      pimlico: process.env.PIMLICO_BUNDLER_URL || `https://api.pimlico.io/v2/8453/rpc?apikey=${PIMLICO_KEY}`,
-    },
-    paymasterUrls: {
-      coinbase: process.env.CDP_PAYMASTER_URL || `https://api.developer.coinbase.com/rpc/v1/base/${CDP_CLIENT_KEY}`,
-      // Pimlico failover paymaster
-      pimlico: process.env.PIMLICO_PAYMASTER_URL || `https://api.pimlico.io/v2/8453/rpc?apikey=${PIMLICO_KEY}`,
-    },
-  },
-};
-
-/**
- * All supported networks
- */
-export const NETWORKS: Record<string, NetworkConfig> = {
-  'base-sepolia': BASE_SEPOLIA,
-  'base-mainnet': BASE_MAINNET
-};
-
-/**
- * Get network configuration by name (returns deep clone to prevent mutation)
- */
-export function getNetwork(network: string): NetworkConfig {
-  const config = NETWORKS[network];
-  if (!config) {
-    throw new Error(
-      `Unknown network: ${network}. Supported networks: ${Object.keys(NETWORKS).join(', ')}`
-    );
-  }
-
-  // Validate that contracts are deployed (not zero addresses)
-  validateNetworkConfig(config);
-
-  // Deep clone to prevent global mutation
-  return {
-    name: config.name,
-    chainId: config.chainId,
-    rpcUrl: config.rpcUrl,
-    blockExplorer: config.blockExplorer,
-    contracts: {
-      actpKernel: config.contracts.actpKernel,
-      escrowVault: config.contracts.escrowVault,
-      usdc: config.contracts.usdc,
-      eas: config.contracts.eas,
-      easSchemaRegistry: config.contracts.easSchemaRegistry,
-      agentRegistry: config.contracts.agentRegistry,
-      identityRegistry: config.contracts.identityRegistry,
-      archiveTreasury: config.contracts.archiveTreasury,
-      x402Relay: config.contracts.x402Relay
-    },
-    eas: {
-      deliverySchemaUID: config.eas.deliverySchemaUID,
-      configSnapshotSchemaUID: config.eas.configSnapshotSchemaUID
-    },
-    gasSettings: {
-      maxFeePerGas: config.gasSettings.maxFeePerGas,
-      maxPriorityFeePerGas: config.gasSettings.maxPriorityFeePerGas
-    },
-    ...(config.aa ? {
-      aa: {
-        entryPoint: config.aa.entryPoint,
-        smartWalletFactory: config.aa.smartWalletFactory,
-        bundlerUrls: { ...config.aa.bundlerUrls },
-        paymasterUrls: { ...config.aa.paymasterUrls },
-      }
-    } : {}),
-  };
-}
-
-/**
- * Validate network name
- */
-export function isValidNetwork(network: string): boolean {
-  return network in NETWORKS;
-}
-
-/**
- * Validate that contract addresses are deployed (not zero addresses)
- *
- * @throws Error if any contract address is zero (0x000...000)
- */
-export function validateNetworkConfig(config: NetworkConfig): void {
-  const zeroAddress = '0x0000000000000000000000000000000000000000';
-  const errors: string[] = [];
-
-  if (config.contracts.actpKernel === zeroAddress) {
-    errors.push('ACTPKernel address is zero - contracts not yet deployed to this network');
-  }
-
-  if (config.contracts.escrowVault === zeroAddress) {
-    errors.push('EscrowVault address is zero - contracts not yet deployed to this network');
-  }
-
-  if (config.contracts.usdc === zeroAddress) {
-    errors.push('USDC address is zero - token contract not configured for this network');
-  }
-
-  if (errors.length > 0) {
-    throw new Error(
-      `Network configuration error for ${config.name} (chainId: ${config.chainId}):\n\n` +
-      errors.map(e => `  ✗ ${e}`).join('\n') +
-      `\n\nContracts must be deployed before using the SDK. Please:\n` +
-      `  1. Deploy contracts to ${config.name}\n` +
-      `  2. Update src/config/networks.ts with deployed addresses\n` +
-      `  3. Rebuild the SDK: npm run build`
-    );
-  }
-}
-