@agirails/sdk 2.2.2 → 2.3.0

package/dist/wallet/keystore.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._clearCache = exports.getCachedAddress = exports.resolvePrivateKey = void 0;
+/**
+ * Keystore auto-resolution for ACTP wallets.
+ *
+ * Resolution order:
+ *   1. ACTP_PRIVATE_KEY env var (backward compat, highest priority)
+ *   2. .actp/keystore.json decrypted with ACTP_KEY_PASSWORD
+ *   3. undefined (caller decides what to do)
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const ethers_1 = require("ethers");
+// Cache keyed by resolved keystorePath to support multiple stateDirectories
+const _cache = new Map();
+// Separate cache for env-var-resolved key (no path dependency)
+let _envCache = null;
+/**
+ * Validate that stateDirectory doesn't escape expected boundaries.
+ * Guards against path traversal when stateDirectory comes from user input.
+ */
+function validateStateDirectory(stateDirectory) {
+    if (stateDirectory.includes('\0')) {
+        throw new Error('Invalid stateDirectory: null byte detected');
+    }
+    // Reject raw '..' in the input (before normalization resolves it)
+    // Catches both relative traversal (../../etc) and embedded traversal (/tmp/../../etc)
+    if (stateDirectory.includes('..')) {
+        throw new Error('Invalid stateDirectory: path traversal detected (..)');
+    }
+}
+/**
+ * Validate and normalize a raw private key string.
+ * Trims whitespace and verifies 0x-prefixed 64-char hex format.
+ */
+function validateRawKey(raw, source) {
+    const trimmed = raw.trim();
+    if (!/^0x[0-9a-fA-F]{64}$/.test(trimmed)) {
+        throw new Error(`Invalid private key from ${source}: expected 0x-prefixed 64-char hex string`);
+    }
+    return trimmed;
+}
+/**
+ * Auto-resolve private key: env var → keystore → undefined.
+ * Never logs or prints the key itself.
+ */
+async function resolvePrivateKey(stateDirectory) {
+    // 1. Env var (highest priority, backward compat)
+    if (process.env.ACTP_PRIVATE_KEY) {
+        if (_envCache)
+            return _envCache.key;
+        const key = validateRawKey(process.env.ACTP_PRIVATE_KEY, 'ACTP_PRIVATE_KEY env var');
+        const address = new ethers_1.Wallet(key).address;
+        _envCache = { key, address };
+        return key;
+    }
+    // 2. Resolve keystore path
+    if (stateDirectory) {
+        validateStateDirectory(stateDirectory);
+    }
+    const actpDir = stateDirectory
+        ? path.join(stateDirectory, '.actp')
+        : path.join(process.cwd(), '.actp');
+    const keystorePath = path.resolve(actpDir, 'keystore.json');
+    // 3. Cache hit (keyed by resolved path)
+    const cached = _cache.get(keystorePath);
+    if (cached)
+        return cached.key;
+    // 4. Keystore file
+    if (!fs.existsSync(keystorePath))
+        return undefined;
+    const password = process.env.ACTP_KEY_PASSWORD;
+    if (!password) {
+        throw new Error('Keystore found at ' + keystorePath + ' but ACTP_KEY_PASSWORD is not set.\n' +
+            'Set it: export ACTP_KEY_PASSWORD="your-password"');
+    }
+    const keystore = fs.readFileSync(keystorePath, 'utf-8');
+    const wallet = await ethers_1.Wallet.fromEncryptedJson(keystore, password);
+    _cache.set(keystorePath, { key: wallet.privateKey, address: wallet.address });
+    return wallet.privateKey;
+}
+exports.resolvePrivateKey = resolvePrivateKey;
+/**
+ * Get cached address from last resolvePrivateKey() call.
+ * Works for both env-var and keystore resolution paths.
+ */
+function getCachedAddress(stateDirectory) {
+    // Env var path
+    if (_envCache)
+        return _envCache.address;
+    // Keystore path — look up by resolved path
+    const actpDir = stateDirectory
+        ? path.join(stateDirectory, '.actp')
+        : path.join(process.cwd(), '.actp');
+    const keystorePath = path.resolve(actpDir, 'keystore.json');
+    return _cache.get(keystorePath)?.address;
+}
+exports.getCachedAddress = getCachedAddress;
+/**
+ * Clear all cached keys and addresses (for testing).
+ * @internal
+ */
+function _clearCache() {
+    _cache.clear();
+    _envCache = null;
+}
+exports._clearCache = _clearCache;
+//# sourceMappingURL=keystore.js.map

package/dist/wallet/keystore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.js","sourceRoot":"","sources":["../../src/wallet/keystore.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agirails/sdk",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "AGIRAILS SDK for the ACTP (Agent Commerce Transaction Protocol) - Unified mock + blockchain support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -80,6 +80,7 @@
     "fast-json-stable-stringify": "2.1.0",
     "kubo-rpc-client": "3.0.1",
     "proper-lockfile": "4.1.2",
+    "yaml": "^2.8.2",
     "zod": "^3.22.4"
   },
   "devDependencies": {

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 {