@agirails/sdk 2.2.2 → 2.3.0

package/src/level1/Agent.ts

@@ -13,6 +13,7 @@ import * as os from 'os';
 import * as fs from 'fs';
 import { ethers } from 'ethers';
 import { ACTPClient } from '../ACTPClient';
+import { resolvePrivateKey } from '../wallet/keystore';
 import { Job, JobHandler, JobContext } from './types/Job';
 import { RequestOptions, RequestResult, NetworkOption } from './types/Options';
 import { PricingStrategy } from './pricing/PricingStrategy';
@@ -386,12 +387,8 @@ export class Agent extends EventEmitter {
     this.emit('starting');
 
     try {
-      // SECURITY FIX (RPCURL): Use rpcUrl from config or fallback to network default
-      // This allows Agent to work with testnet/mainnet without requiring explicit rpcUrl
-      // if user is okay with public RPC endpoints.
       let rpcUrl = this.config.rpcUrl;
       if (!rpcUrl && (this.network === 'testnet' || this.network === 'mainnet')) {
-        // Import getNetwork to get default rpcUrl from network config
         const { getNetwork } = await import('../config/networks');
         const networkName = this.network === 'testnet' ? 'base-sepolia' : 'base-mainnet';
         const networkConfig = getNetwork(networkName);
@@ -399,16 +396,14 @@ export class Agent extends EventEmitter {
         this.logger.info(`Using default RPC URL for ${networkName}: ${rpcUrl}`);
       }
 
-      // Initialize ACTP client
       this._client = await ACTPClient.create({
         mode: this.network === 'testnet' ? 'testnet' : this.network === 'mainnet' ? 'mainnet' : 'mock',
-        requesterAddress: this.address || this.generateAddress(),
+        requesterAddress: this.address || await this.generateAddress(),
         stateDirectory: this.config.stateDirectory,
-        privateKey: this.getPrivateKey(),
+        privateKey: await this.getPrivateKey(),
         rpcUrl,
       });
 
-      // Start polling for jobs
       this.startPolling();
 
       this._status = 'running';
@@ -1371,15 +1366,8 @@ export class Agent extends EventEmitter {
     }
   }
 
-  /**
-   * Generate address based on wallet configuration
-   *
-   * SECURITY FIX (HIGH): For testnet/mainnet, MUST derive from private key.
-   * For mock mode, can use deterministic address for convenience.
-   */
-  private generateAddress(): string {
-    // If wallet has private key, ALWAYS derive address from it
-    const privateKey = this.getPrivateKey();
+  private async generateAddress(): Promise<string> {
+    const privateKey = await this.getPrivateKey();
     if (privateKey) {
       try {
         const wallet = new ethers.Wallet(privateKey);
@@ -1389,33 +1377,31 @@ export class Agent extends EventEmitter {
       }
     }
 
-    // For non-mock networks, require a valid private key or address
     if (this.network === 'testnet' || this.network === 'mainnet') {
       throw new ValidationError(
         'wallet',
-        `${this.network} mode requires a valid private key or address in wallet configuration`
+        `${this.network} mode requires a valid private key or address in wallet configuration.\n` +
+        'Run "actp init" to generate a keystore, or set ACTP_PRIVATE_KEY env var.'
       );
     }
 
-    // For mock mode only: generate deterministic address from agent name
-    // This is safe because mock mode doesn't involve real funds
     return `0x${Buffer.from(this.name).toString('hex').padEnd(40, '0').slice(0, 40)}`;
   }
 
-  /**
-   * Get private key from configuration
-   *
-   * SECURITY FIX (HIGH): Validate private key format before use
-   */
-  private getPrivateKey(): string | undefined {
-    if (!this.config.wallet || this.config.wallet === 'auto' || this.config.wallet === 'connect') {
+  private async getPrivateKey(): Promise<string | undefined> {
+    if (!this.config.wallet || this.config.wallet === 'auto') {
+      if (this.network === 'testnet' || this.network === 'mainnet') {
+        return resolvePrivateKey(this.config.stateDirectory);
+      }
+      return undefined;
+    }
+
+    if (this.config.wallet === 'connect') {
       return undefined;
     }
 
     if (typeof this.config.wallet === 'string') {
-      // Check if it looks like a private key (0x + 64 hex chars)
       if (/^0x[0-9a-fA-F]{64}$/.test(this.config.wallet)) {
-        // Validate by trying to create a wallet
         try {
           new ethers.Wallet(this.config.wallet);
           return this.config.wallet;
@@ -1423,11 +1409,9 @@ export class Agent extends EventEmitter {
           throw new ValidationError('wallet', 'Invalid private key format');
         }
       }
-      // It's an address, not a private key
       return undefined;
     }
 
-    // Validate private key format
     if (this.config.wallet.privateKey) {
       try {
         new ethers.Wallet(this.config.wallet.privateKey);

package/src/registry/AgentRegistryClient.ts

@@ -0,0 +1,202 @@
+/**
+ * AgentRegistryClient - Thin wrapper for AgentRegistry v2 config operations
+ *
+ * Provides methods for:
+ * - Publishing AGIRAILS.md config (CID + hash) on-chain
+ * - Managing launchpad listing visibility
+ * - Reading config state for any agent
+ *
+ * @module registry/AgentRegistryClient
+ */
+
+import { Contract, Signer, Provider } from 'ethers';
+import AgentRegistryABI from '../abi/AgentRegistry.json';
+import { ValidationError, TransactionRevertedError } from '../errors';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AgentConfigState {
+  configHash: string;
+  configCID: string;
+  listed: boolean;
+  isActive: boolean;
+  updatedAt: number;
+}
+
+export interface PublishConfigResult {
+  txHash: string;
+}
+
+interface GasOptions {
+  maxFeePerGas?: bigint;
+  maxPriorityFeePerGas?: bigint;
+}
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export class AgentRegistryClient {
+  private contract: Contract;
+  private readonlyContract: Contract;
+
+  constructor(
+    private readonly registryAddress: string,
+    private readonly signer: Signer,
+    private readonly gasSettings?: GasOptions
+  ) {
+    this.contract = new Contract(registryAddress, AgentRegistryABI, signer);
+    this.readonlyContract = this.contract;
+  }
+
+  /**
+   * Create a read-only client (no signer required)
+   */
+  static readOnly(registryAddress: string, provider: Provider): AgentRegistryClient {
+    // Create a minimal signer-like object for the contract
+    // but only the readonly contract will be used
+    const contract = new Contract(registryAddress, AgentRegistryABI, provider);
+    const client = Object.create(AgentRegistryClient.prototype);
+    client.registryAddress = registryAddress;
+    client.readonlyContract = contract;
+    client.contract = null; // Write operations will throw
+    return client;
+  }
+
+  // ========== WRITE OPERATIONS ==========
+
+  /**
+   * Publish config (AGIRAILS.md) on-chain
+   *
+   * @param cid - IPFS CID pointing to the AGIRAILS.md file
+   * @param hash - keccak256 of canonical AGIRAILS.md content (bytes32)
+   * @returns Transaction hash
+   */
+  async publishConfig(cid: string, hash: string): Promise<PublishConfigResult> {
+    if (!this.contract) {
+      throw new Error('Write operations require a signer. Use AgentRegistryClient constructor, not readOnly().');
+    }
+
+    if (!cid || cid.length === 0) {
+      throw new ValidationError('cid', 'IPFS CID is required');
+    }
+    if (cid.length > 128) {
+      throw new ValidationError('cid', 'CID too long (max 128 characters)');
+    }
+    if (!hash || hash === '0x' + '0'.repeat(64)) {
+      throw new ValidationError('hash', 'Config hash is required (cannot be zero)');
+    }
+    if (!/^0x[a-fA-F0-9]{64}$/.test(hash)) {
+      throw new ValidationError('hash', 'Config hash must be a valid bytes32 hex string');
+    }
+
+    try {
+      const estimatedGas = await this.contract.publishConfig.estimateGas(cid, hash);
+      const gasLimit = (estimatedGas * 120n) / 100n; // 20% buffer
+
+      const txOptions: Record<string, unknown> = { gasLimit };
+      if (this.gasSettings?.maxFeePerGas) {
+        txOptions.maxFeePerGas = this.gasSettings.maxFeePerGas;
+      }
+      if (this.gasSettings?.maxPriorityFeePerGas) {
+        txOptions.maxPriorityFeePerGas = this.gasSettings.maxPriorityFeePerGas;
+      }
+
+      const tx = await this.contract.publishConfig(cid, hash, txOptions);
+      const receipt = await tx.wait();
+
+      return { txHash: receipt.hash };
+    } catch (error: unknown) {
+      if (error instanceof Error && error.message.includes('Not registered')) {
+        throw new TransactionRevertedError(
+          'Agent not registered. Register first using the AgentRegistry before publishing config.',
+          'publishConfig'
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Set launchpad listing visibility
+   *
+   * @param listed - Whether agent should be visible on launchpad
+   * @returns Transaction hash
+   */
+  async setListed(listed: boolean): Promise<string> {
+    if (!this.contract) {
+      throw new Error('Write operations require a signer. Use AgentRegistryClient constructor, not readOnly().');
+    }
+
+    try {
+      const estimatedGas = await this.contract.setListed.estimateGas(listed);
+      const gasLimit = (estimatedGas * 115n) / 100n; // 15% buffer
+
+      const txOptions: Record<string, unknown> = { gasLimit };
+      if (this.gasSettings?.maxFeePerGas) {
+        txOptions.maxFeePerGas = this.gasSettings.maxFeePerGas;
+      }
+      if (this.gasSettings?.maxPriorityFeePerGas) {
+        txOptions.maxPriorityFeePerGas = this.gasSettings.maxPriorityFeePerGas;
+      }
+
+      const tx = await this.contract.setListed(listed, txOptions);
+      const receipt = await tx.wait();
+
+      return receipt.hash;
+    } catch (error: unknown) {
+      if (error instanceof Error && error.message.includes('Not registered')) {
+        throw new TransactionRevertedError(
+          'Agent not registered. Register first before setting listing status.',
+          'setListed'
+        );
+      }
+      throw error;
+    }
+  }
+
+  // ========== READ OPERATIONS ==========
+
+  /**
+   * Get config state for an agent
+   *
+   * @param agentAddress - Agent's Ethereum address
+   * @returns Config state (hash, CID, listed, isActive, updatedAt)
+   */
+  async getConfig(agentAddress: string): Promise<AgentConfigState> {
+    const contract = this.readonlyContract || this.contract;
+    const profile = await contract.getAgent(agentAddress);
+
+    return {
+      configHash: profile.configHash,
+      configCID: profile.configCID,
+      listed: profile.listed,
+      isActive: profile.isActive,
+      updatedAt: Number(profile.updatedAt),
+    };
+  }
+
+  /**
+   * Check if an agent is listed on the launchpad
+   *
+   * @param agentAddress - Agent's Ethereum address
+   * @returns true if agent is listed
+   */
+  async isListed(agentAddress: string): Promise<boolean> {
+    const config = await this.getConfig(agentAddress);
+    return config.listed;
+  }
+
+  /**
+   * Get the on-chain config hash for an agent
+   *
+   * @param agentAddress - Agent's Ethereum address
+   * @returns Config hash (bytes32) or zero hash if not published
+   */
+  async getConfigHash(agentAddress: string): Promise<string> {
+    const config = await this.getConfig(agentAddress);
+    return config.configHash;
+  }
+}

package/src/runtime/MockRuntime.ts

@@ -646,7 +646,9 @@ export class MockRuntime implements IACTPRuntime {
       if (newState === 'DELIVERED') {
         tx.completedAt = currentTime;
         // SECURITY FIX (PROOF-PARAM): Store delivery proof if provided
-        if (proof) {
+        // Only set if not already populated (Agent sets deliveryProof before transitioning,
+        // and passes disputeWindowProof as the proof param — don't overwrite the real proof)
+        if (proof && !tx.deliveryProof) {
           tx.deliveryProof = proof;
         }
       }

package/src/types/adapter.ts

@@ -11,6 +11,7 @@
  */
 
 import { z } from 'zod';
+import type { X402FeeBreakdown } from './x402';
 
 // ============================================================================
 // AdapterMetadata - Describes adapter capabilities
@@ -249,6 +250,12 @@ export interface UnifiedPayResult {
    * Use with ReputationReporter.reportSettlement() after release.
    */
   erc8004AgentId?: string;
+
+  /**
+   * Fee breakdown for x402 payments routed through X402Relay.
+   * Present only when relay is configured and payment used the relay path.
+   */
+  feeBreakdown?: X402FeeBreakdown;
 }
 
 /**
@@ -268,6 +275,13 @@ export const UnifiedPayResultSchema = z.object({
   requester: z.string().min(1),
   deadline: z.string().min(1),
   erc8004AgentId: z.string().optional(),
+  feeBreakdown: z.object({
+    grossAmount: z.string(),
+    providerNet: z.string(),
+    platformFee: z.string(),
+    feeBps: z.number(),
+    estimated: z.literal(true),
+  }).optional(),
 });
 
 // ============================================================================

package/src/types/x402.ts

@@ -194,6 +194,38 @@ export class X402Error extends Error {
   }
 }
 
+// ============================================================================
+// Fee Types
+// ============================================================================
+
+/**
+ * Fee breakdown for x402 payments routed through X402Relay.
+ *
+ * Shows how the gross amount was split between provider and platform.
+ * Fee = max(grossAmount * feeBps / 10000, MIN_FEE).
+ *
+ * NOTE: This is a client-side **estimate** computed from the configured
+ * platformFeeBps. The on-chain X402Relay contract is the source of truth.
+ * If an admin updates the relay's fee rate, this estimate may diverge
+ * from the actual on-chain split until the SDK config is refreshed.
+ */
+export interface X402FeeBreakdown {
+  /** Total amount from the 402 header (USDC wei, 6 decimals) */
+  grossAmount: string;
+
+  /** Estimated amount provider received: grossAmount - platformFee */
+  providerNet: string;
+
+  /** Estimated amount treasury received: max(feeBps%, $0.05) */
+  platformFee: string;
+
+  /** Fee rate used for estimate (basis points, e.g. 100 = 1%) */
+  feeBps: number;
+
+  /** True — this is a client-side estimate, not read from chain */
+  estimated: true;
+}
+
 // ============================================================================
 // Type Guards
 // ============================================================================

package/src/wallet/keystore.ts

@@ -0,0 +1,119 @@
+/**
+ * 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)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { Wallet } from 'ethers';
+
+// Cache keyed by resolved keystorePath to support multiple stateDirectories
+const _cache = new Map<string, { key: string; address: string }>();
+
+// Separate cache for env-var-resolved key (no path dependency)
+let _envCache: { key: string; address: string } | null = null;
+
+/**
+ * Validate that stateDirectory doesn't escape expected boundaries.
+ * Guards against path traversal when stateDirectory comes from user input.
+ */
+function validateStateDirectory(stateDirectory: string): void {
+  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: string, source: string): string {
+  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.
+ */
+export async function resolvePrivateKey(
+  stateDirectory?: string
+): Promise<string | undefined> {
+  // 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 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 Wallet.fromEncryptedJson(keystore, password);
+
+  _cache.set(keystorePath, { key: wallet.privateKey, address: wallet.address });
+  return wallet.privateKey;
+}
+
+/**
+ * Get cached address from last resolvePrivateKey() call.
+ * Works for both env-var and keystore resolution paths.
+ */
+export function getCachedAddress(stateDirectory?: string): string | undefined {
+  // 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;
+}
+
+/**
+ * Clear all cached keys and addresses (for testing).
+ * @internal
+ */
+export function _clearCache(): void {
+  _cache.clear();
+  _envCache = null;
+}