@agirails/sdk 2.2.3 → 2.3.0

package/src/ACTPClient.ts

@@ -655,7 +655,16 @@ export class ACTPClient {
 
     // SECURITY FIX (C-4): Pass EASHelper to adapters for attestation verification
     // ERC-8004: Pass bridge for agent ID resolution, reporter for settlement outcomes
-    return new ACTPClient(runtime, normalizedAddress, info, easHelper, erc8004Bridge, reputationReporter);
+    const client = new ACTPClient(runtime, normalizedAddress, info, easHelper, erc8004Bridge, reputationReporter);
+
+    // Drift detection: non-blocking check for AGIRAILS.md sync status
+    if (config.mode !== 'mock') {
+      client.checkConfigDrift(config).catch(() => {
+        // Silently ignore drift check errors — non-critical
+      });
+    }
+
+    return client;
   }
 
   // ==========================================================================
@@ -1103,4 +1112,57 @@ export class ACTPClient {
   getReputationReporter(): ReputationReporter | undefined {
     return this.reputationReporter;
   }
+
+  /**
+   * Non-blocking drift detection for AGIRAILS.md config.
+   * Checks if local AGIRAILS.md matches on-chain config hash.
+   * Logs warnings but never blocks agent operation.
+   * @internal
+   */
+  private async checkConfigDrift(config: ACTPClientConfig): Promise<void> {
+    try {
+      const { existsSync, readFileSync } = await import('fs');
+      const { join } = await import('path');
+
+      // Look for AGIRAILS.md in cwd
+      const agirailsMdPath = join(process.cwd(), 'AGIRAILS.md');
+      if (!existsSync(agirailsMdPath)) {
+        return; // No local file — nothing to check
+      }
+
+      const network = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+      const networkConfig = getNetwork(network);
+      if (!networkConfig.contracts.agentRegistry) {
+        return; // No registry on this network
+      }
+
+      const content = readFileSync(agirailsMdPath, 'utf-8');
+      const { computeConfigHash } = await import('./config/agirailsmd');
+      const { configHash: localHash } = computeConfigHash(content);
+
+      const { AgentRegistryClient } = await import('./registry/AgentRegistryClient');
+      const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
+      const registryClient = AgentRegistryClient.readOnly(networkConfig.contracts.agentRegistry, provider);
+
+      // Detect template vs published state from frontmatter
+      const { parseAgirailsMd: parseMd } = await import('./config/agirailsmd');
+      const { frontmatter } = parseMd(content);
+      const isTemplate = !frontmatter.config_hash;
+
+      const onChainState = await registryClient.getConfig(config.requesterAddress);
+      const ZERO_HASH = '0x' + '0'.repeat(64);
+
+      if (onChainState.configHash === ZERO_HASH) {
+        if (isTemplate) {
+          console.info('[AGIRAILS] AGIRAILS.md loaded (template mode). Run "actp publish" to register and sync on-chain.');
+        } else {
+          console.warn('[AGIRAILS] Config not published on-chain. Run: actp publish');
+        }
+      } else if (onChainState.configHash !== localHash) {
+        console.warn('[AGIRAILS] Local AGIRAILS.md differs from on-chain. Run: actp diff');
+      }
+    } catch {
+      // Silently ignore — drift detection is best-effort
+    }
+  }
 }

package/src/abi/AgentRegistry.json

@@ -10,6 +10,19 @@
     ],
     "stateMutability": "nonpayable"
   },
+  {
+    "type": "function",
+    "name": "MAX_CID_LENGTH",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "stateMutability": "view"
+  },
   {
     "type": "function",
     "name": "MAX_ENDPOINT_LENGTH",
@@ -166,6 +179,21 @@
         "name": "isActive",
         "type": "bool",
         "internalType": "bool"
+      },
+      {
+        "name": "configHash",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "configCID",
+        "type": "string",
+        "internalType": "string"
+      },
+      {
+        "name": "listed",
+        "type": "bool",
+        "internalType": "bool"
       }
     ],
     "stateMutability": "view"
@@ -277,6 +305,21 @@
             "name": "isActive",
             "type": "bool",
             "internalType": "bool"
+          },
+          {
+            "name": "configHash",
+            "type": "bytes32",
+            "internalType": "bytes32"
+          },
+          {
+            "name": "configCID",
+            "type": "string",
+            "internalType": "string"
+          },
+          {
+            "name": "listed",
+            "type": "bool",
+            "internalType": "bool"
           }
         ]
       }
@@ -358,6 +401,21 @@
             "name": "isActive",
             "type": "bool",
             "internalType": "bool"
+          },
+          {
+            "name": "configHash",
+            "type": "bytes32",
+            "internalType": "bytes32"
+          },
+          {
+            "name": "configCID",
+            "type": "string",
+            "internalType": "string"
+          },
+          {
+            "name": "listed",
+            "type": "bool",
+            "internalType": "bool"
           }
         ]
       }
@@ -420,6 +478,24 @@
     ],
     "stateMutability": "view"
   },
+  {
+    "type": "function",
+    "name": "publishConfig",
+    "inputs": [
+      {
+        "name": "cid",
+        "type": "string",
+        "internalType": "string"
+      },
+      {
+        "name": "hash",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
   {
     "type": "function",
     "name": "queryAgentsByService",
@@ -535,6 +611,19 @@
     "outputs": [],
     "stateMutability": "nonpayable"
   },
+  {
+    "type": "function",
+    "name": "setListed",
+    "inputs": [
+      {
+        "name": "_listed",
+        "type": "bool",
+        "internalType": "bool"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
   {
     "type": "function",
     "name": "supportsService",
@@ -656,6 +745,31 @@
     ],
     "anonymous": false
   },
+  {
+    "type": "event",
+    "name": "ConfigPublished",
+    "inputs": [
+      {
+        "name": "agent",
+        "type": "address",
+        "indexed": true,
+        "internalType": "address"
+      },
+      {
+        "name": "configCID",
+        "type": "string",
+        "indexed": false,
+        "internalType": "string"
+      },
+      {
+        "name": "configHash",
+        "type": "bytes32",
+        "indexed": false,
+        "internalType": "bytes32"
+      }
+    ],
+    "anonymous": false
+  },
   {
     "type": "event",
     "name": "EndpointUpdated",
@@ -687,6 +801,25 @@
     ],
     "anonymous": false
   },
+  {
+    "type": "event",
+    "name": "ListingChanged",
+    "inputs": [
+      {
+        "name": "agent",
+        "type": "address",
+        "indexed": true,
+        "internalType": "address"
+      },
+      {
+        "name": "listed",
+        "type": "bool",
+        "indexed": false,
+        "internalType": "bool"
+      }
+    ],
+    "anonymous": false
+  },
   {
     "type": "event",
     "name": "ReputationUpdated",

package/src/adapters/X402Adapter.ts

@@ -35,6 +35,7 @@ import {
   X402Error,
   X402ErrorCode,
   X402Network,
+  X402FeeBreakdown,
   isValidX402Network,
 } from '../types/x402';
 
@@ -46,14 +47,33 @@ import {
 export type FetchFunction = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
 /**
- * Transfer function for atomic payments.
- * 
+ * Transfer function for atomic payments (legacy direct transfer).
+ *
  * @param to - Recipient address
  * @param amount - Amount in USDC wei (string)
  * @returns Transaction hash as proof
  */
 export type TransferFunction = (to: string, amount: string) => Promise<string>;
 
+/**
+ * Approve function for USDC allowance (used with X402Relay).
+ *
+ * @param spender - Spender address (relay contract)
+ * @param amount - Amount in USDC wei (string)
+ * @returns Transaction hash
+ */
+export type ApproveFunction = (spender: string, amount: string) => Promise<string>;
+
+/**
+ * Relay pay function — calls X402Relay.payWithFee().
+ *
+ * @param provider - Provider address
+ * @param grossAmount - Gross USDC amount (string)
+ * @param serviceId - Service identifier (bytes32 hex)
+ * @returns Transaction hash
+ */
+export type RelayPayFunction = (provider: string, grossAmount: string, serviceId: string) => Promise<string>;
+
 /** Supported HTTP methods for x402 requests */
 export type X402HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 
@@ -76,12 +96,15 @@ export interface X402PayParams extends UnifiedPayParams {
 
 /**
  * Configuration options for X402Adapter.
+ *
+ * For fee-enabled payments via X402Relay, provide relayAddress + approveFn + relayPayFn.
+ * Without relay config, falls back to legacy direct transfer (no platform fee).
  */
 export interface X402AdapterConfig {
   /** Expected network for validation (must match server's X-Payment-Network) */
   expectedNetwork: X402Network;
 
-  /** Transfer function for atomic payments (required) */
+  /** Transfer function for direct atomic payments (legacy fallback) */
   transferFn: TransferFunction;
 
   /** Request timeout in milliseconds (default: 30000) */
@@ -92,6 +115,20 @@ export interface X402AdapterConfig {
 
   /** Default headers to include in all requests */
   defaultHeaders?: Record<string, string>;
+
+  // --- X402Relay fee-splitting (optional, recommended) ---
+
+  /** X402Relay contract address for on-chain fee splitting */
+  relayAddress?: string;
+
+  /** USDC approve function — required when relayAddress is set */
+  approveFn?: ApproveFunction;
+
+  /** Relay payWithFee function — required when relayAddress is set */
+  relayPayFn?: RelayPayFunction;
+
+  /** Platform fee in basis points (default: 100 = 1%). Read-only display hint. */
+  platformFeeBps?: number;
 }
 
 /**
@@ -104,6 +141,7 @@ interface AtomicPaymentRecord {
   amount: string;
   timestamp: number;
   endpoint: string;
+  feeBreakdown?: X402FeeBreakdown;
 }
 
 // ============================================================================
@@ -287,15 +325,15 @@ export class X402Adapter extends BaseAdapter implements IAdapter {
       );
     }
 
-    // Step 6: ATOMIC PAYMENT - direct transfer, no escrow
-    const txHash = await this.executeAtomicPayment(paymentHeaders);
+    // Step 6: ATOMIC PAYMENT - via relay (with fee) or direct transfer (legacy)
+    const { txHash, feeBreakdown } = await this.executeAtomicPayment(paymentHeaders);
 
     // Step 7: Retry with proof (same method/headers/body + payment proof)
     const serviceResponse = await this.retryWithProof(
-      endpoint, 
-      txHash, 
-      method, 
-      requestHeaders, 
+      endpoint,
+      txHash,
+      method,
+      requestHeaders,
       requestBody,
       contentType
     );
@@ -308,6 +346,7 @@ export class X402Adapter extends BaseAdapter implements IAdapter {
       amount: paymentHeaders.amount,
       timestamp: now,
       endpoint,
+      feeBreakdown,
     });
 
     // Step 9: Return result - DONE! No release needed.
@@ -323,6 +362,7 @@ export class X402Adapter extends BaseAdapter implements IAdapter {
       provider: paymentHeaders.paymentAddress.toLowerCase(),
       requester: this.requesterAddress.toLowerCase(),
       deadline: new Date(paymentHeaders.deadline * 1000).toISOString(),
+      feeBreakdown,
     };
   }
 
@@ -562,20 +602,58 @@ export class X402Adapter extends BaseAdapter implements IAdapter {
   }
 
   /**
-   * Execute atomic payment - direct transfer to provider.
+   * Execute atomic payment with fee splitting via X402Relay (if configured),
+   * or direct transfer as legacy fallback.
    *
-   * This is the key difference from ACTP:
-   * - No escrow
-   * - No state machine
-   * - Just transfer and done
+   * Relay flow: approve relay → relay.payWithFee(provider, gross, serviceId)
+   * Legacy flow: transferFn(provider, amount) — no fee extraction
    */
-  private async executeAtomicPayment(headers: X402PaymentHeaders): Promise<string> {
+  private async executeAtomicPayment(headers: X402PaymentHeaders): Promise<{
+    txHash: string;
+    feeBreakdown?: X402FeeBreakdown;
+  }> {
     try {
+      // Relay path: on-chain fee splitting
+      if (this.config.relayAddress && this.config.approveFn && this.config.relayPayFn) {
+        const grossAmount = headers.amount;
+        const feeBps = this.config.platformFeeBps ?? 100;
+        const MIN_FEE = 50_000n; // $0.05 USDC
+
+        // Calculate fee: max(gross * bps / 10000, MIN_FEE)
+        const grossBig = BigInt(grossAmount);
+        const bpsFee = (grossBig * BigInt(feeBps)) / 10_000n;
+        const fee = bpsFee > MIN_FEE ? bpsFee : MIN_FEE;
+        const providerNet = grossBig - fee;
+
+        // 1. Approve relay for gross amount
+        await this.config.approveFn(this.config.relayAddress, grossAmount);
+
+        // 2. Call relay.payWithFee
+        const serviceId = headers.serviceId ?? '0x' + '0'.repeat(64);
+        const txHash = await this.config.relayPayFn(
+          headers.paymentAddress,
+          grossAmount,
+          serviceId
+        );
+
+        return {
+          txHash,
+          feeBreakdown: {
+            grossAmount,
+            providerNet: providerNet.toString(),
+            platformFee: fee.toString(),
+            feeBps,
+            estimated: true,
+          },
+        };
+      }
+
+      // Legacy path: direct transfer, no fee
       const txHash = await this.transferFn(
         headers.paymentAddress,
         headers.amount
       );
-      return txHash;
+      return { txHash };
     } catch (error) {
       throw new X402Error(
         `Atomic payment failed: ${error instanceof Error ? error.message : 'Unknown error'}`,

package/src/adapters/index.ts

@@ -23,7 +23,15 @@ export {
 } from './BaseAdapter';
 export { BasicAdapter, BasicPayParams, BasicPayResult } from './BasicAdapter';
 export { StandardAdapter, StandardTransactionParams } from './StandardAdapter';
-export { X402Adapter, X402AdapterConfig, FetchFunction } from './X402Adapter';
+export {
+  X402Adapter,
+  X402AdapterConfig,
+  X402PayParams,
+  X402HttpMethod,
+  FetchFunction,
+  ApproveFunction,
+  RelayPayFunction,
+} from './X402Adapter';
 export { AdapterRegistry } from './AdapterRegistry';
 export { AdapterRouter, AdapterSelectionResult } from './AdapterRouter';
 export {

package/src/cli/commands/diff.ts

@@ -0,0 +1,141 @@
+/**
+ * Diff Command - Compare local AGIRAILS.md with on-chain config
+ *
+ * Shows sync status between local file and AgentRegistry state.
+ * Terraform-style: never auto-overwrites, just shows differences.
+ *
+ * @module cli/commands/diff
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { mapError } from '../utils/client';
+import { resolve } from 'path';
+import { ethers } from 'ethers';
+import { diff } from '../../config/syncOperations';
+import { getNetwork } from '../../config/networks';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createDiffCommand(): Command {
+  const cmd = new Command('diff')
+    .description('Compare local AGIRAILS.md with on-chain config')
+    .argument('[path]', 'Path to AGIRAILS.md', './AGIRAILS.md')
+    .option('-n, --network <network>', 'Network (base-sepolia | base-mainnet)', 'base-sepolia')
+    .option('-a, --address <address>', 'Agent address to compare with')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only sync status')
+    .action(async (path, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runDiff(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 DiffCommandOptions {
+  network: string;
+  address?: string;
+}
+
+async function runDiff(
+  filePath: string,
+  options: DiffCommandOptions,
+  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('Comparing local and on-chain config...');
+
+  try {
+    const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
+
+    const result = await diff({
+      path: resolvedPath,
+      agentAddress,
+      registryAddress: networkConfig.contracts.agentRegistry,
+      provider,
+    });
+
+    spinner.stop(true);
+
+    output.result(
+      {
+        status: result.status,
+        inSync: result.inSync,
+        localHash: result.localHash,
+        onChainHash: result.onChainHash,
+        onChainCID: result.onChainCID || null,
+        hasLocalFile: result.hasLocalFile,
+        hasOnChainConfig: result.hasOnChainConfig,
+        network: options.network,
+        agent: agentAddress,
+      },
+      { quietKey: 'status' }
+    );
+
+    output.blank();
+
+    // Human-friendly status messages
+    switch (result.status) {
+      case 'in-sync':
+        output.success('Local and on-chain configs are in sync.');
+        break;
+      case 'local-ahead':
+        output.warning('Local changes not yet published. Run: actp publish');
+        break;
+      case 'remote-ahead':
+        output.warning('On-chain config is newer. Run: actp pull');
+        break;
+      case 'diverged':
+        output.warning('Local and on-chain configs have diverged.');
+        output.print('  Resolve by running: actp publish (to push local) or actp pull --force (to accept remote)');
+        break;
+      case 'no-local':
+        output.info('No local AGIRAILS.md found. Run: actp pull');
+        break;
+      case 'no-remote':
+        output.info('No config published on-chain. Run: actp publish');
+        break;
+    }
+  } catch (error) {
+    spinner.stop(false);
+    throw error;
+  }
+}

package/src/cli/commands/init.ts

@@ -10,6 +10,7 @@
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as readline from 'readline';
 import { Command } from 'commander';
 import {
   saveConfig,
@@ -102,10 +103,10 @@ async function runInit(options: InitOptions, output: Output): Promise<void> {
       address = '0x' + crypto.randomBytes(20).toString('hex');
       output.info(`Generated mock address: ${address}`);
     } else {
-      throw new Error(
-        `Address required for ${mode} mode.\n` +
-          'Use --address <your-address> to specify.'
-      );
+      // Generate a real wallet with encrypted keystore
+      const actpDir = getActpDir(projectRoot);
+      fs.mkdirSync(actpDir, { recursive: true });
+      address = await generateWallet(actpDir, output);
     }
   }
 
@@ -177,6 +178,66 @@ async function runInit(options: InitOptions, output: Output): Promise<void> {
   }
 }
 
+// ============================================================================
+// Wallet Generation
+// ============================================================================
+
+async function generateWallet(actpDir: string, output: Output): Promise<string> {
+  const { Wallet } = await import('ethers');
+
+  const wallet = Wallet.createRandom();
+
+  // Get password from env var or interactive prompt
+  let password = process.env.ACTP_KEY_PASSWORD;
+  if (!password) {
+    password = await promptPassword();
+  }
+
+  if (!password || password.length < 8) {
+    throw new Error(
+      'Wallet password required (minimum 8 characters).\n' +
+        'Set ACTP_KEY_PASSWORD env var or enter when prompted.'
+    );
+  }
+
+  // Encrypt with Keystore V3 (scrypt + AES-128-CTR)
+  output.info('Encrypting wallet (this takes a few seconds)...');
+  const keystore = await wallet.encrypt(password);
+
+  // Save with restrictive permissions
+  const keystorePath = path.join(actpDir, 'keystore.json');
+  fs.writeFileSync(keystorePath, keystore, { mode: 0o600 });
+
+  output.success('Key securely saved and encrypted');
+  output.info(`Address: ${wallet.address}`);
+  output.warning('Back up your password — it cannot be recovered.');
+  output.info('');
+  output.info('To start your agent:');
+  output.info('  export ACTP_KEY_PASSWORD="your-password"');
+  output.info('  npx ts-node agent.ts');
+
+  return wallet.address;
+}
+
+async function promptPassword(): Promise<string> {
+  // If not a TTY (e.g. piped or run by agent), skip prompt
+  if (!process.stdin.isTTY) {
+    return '';
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question('Enter password for wallet encryption (min 8 chars): ', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
 // ============================================================================
 // Scaffold
 // ============================================================================