@agirails/sdk 2.2.3 → 2.3.1

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/BlockchainRuntime.ts

@@ -65,6 +65,11 @@ export interface BlockchainRuntimeConfig {
    * If provided, attestation replay protection will survive restarts
    */
   stateDirectory?: string;
+  /**
+   * Number of block confirmations to wait after each state-changing tx.
+   * Default: 2 (Base L2 reorg safety). Set to 1 on testnet for speed.
+   */
+  confirmations?: number;
 }
 
 /**
@@ -163,7 +168,8 @@ export class BlockchainRuntime implements IACTPRuntime {
     this.kernel = new ACTPKernel(
       this.networkConfig.contracts.actpKernel,
       this.signer,
-      config.gasSettings
+      config.gasSettings,
+      config.confirmations
     );
 
     this.escrow = new EscrowVault(

package/src/storage/ArchiveBundleBuilder.ts

@@ -15,14 +15,12 @@ import { ValidationError } from '../errors';
 import {
   ArchiveBundle,
   ArchiveChainId,
-  ArchiveFinalState,
   ArchiveParticipants,
   ArchiveReferences,
   ArchiveHashes,
   ArchiveSignatures,
   ArchiveAttestation,
   ArchiveSettlement,
-  EscrowRelease,
   ARCHIVE_BUNDLE_TYPE
 } from './types';
 

package/src/storage/ArweaveClient.ts

@@ -48,7 +48,6 @@ import {
 import { withRetry, RetryOptions } from '../utils/retry';
 import {
   GatewayCircuitBreaker,
-  CircuitBreakerConfig
 } from '../utils/circuitBreaker';
 
 // ============================================================================
@@ -538,6 +537,7 @@ export class ArweaveClient {
           const chunks: Uint8Array[] = [];
           let totalSize = 0;
 
+          // eslint-disable-next-line no-constant-condition
           while (true) {
             const { done, value } = await reader.read();
             if (done) break;
@@ -671,6 +671,7 @@ export class ArweaveClient {
           const chunks: Uint8Array[] = [];
           let totalSize = 0;
 
+          // eslint-disable-next-line no-constant-condition
           while (true) {
             const { done, value } = await reader.read();
             if (done) break;

package/src/storage/FilebaseClient.ts

@@ -14,7 +14,7 @@
  * @module storage/FilebaseClient
  */
 
-import { S3Client, PutObjectCommand, GetObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import { S3Client, PutObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
 import {
   StorageError,
   StorageAuthenticationError,
@@ -39,8 +39,6 @@ import {
 import { withRetry, RetryOptions } from '../utils/retry';
 import {
   GatewayCircuitBreaker,
-  CircuitBreakerConfig,
-  globalCircuitBreaker
 } from '../utils/circuitBreaker';
 
 // ============================================================================
@@ -329,6 +327,7 @@ export class FilebaseClient {
           const chunks: Uint8Array[] = [];
           let totalSize = 0;
 
+          // eslint-disable-next-line no-constant-condition
           while (true) {
             const { done, value } = await reader.read();
             if (done) break;
@@ -516,6 +515,7 @@ export class FilebaseClient {
           const chunks: Uint8Array[] = [];
           let totalSize = 0;
 
+          // eslint-disable-next-line no-constant-condition
           while (true) {
             const { done, value } = await reader.read();
             if (done) break;

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/utils/ErrorRecoveryGuide.ts

@@ -7,6 +7,8 @@
  * @module utils/ErrorRecoveryGuide
  */
 
+import { sdkLogger } from './Logger';
+
 /**
  * Error severity levels for prioritization
  */
@@ -650,14 +652,14 @@ export async function withRecoveryGuidance<T>(
       }
 
       if (logGuidance) {
-        console.error(ErrorRecoveryGuide.formatGuidance(error));
+        sdkLogger.error(ErrorRecoveryGuide.formatGuidance(error));
       }
 
       if (autoRetry && recovery.retryable) {
         const retryParams = ErrorRecoveryGuide.getRetryParams(error);
         if (retryParams && attempts < retryParams.maxRetries) {
           attempts++;
-          console.log(
+          sdkLogger.info(
             `Retrying (${attempts}/${retryParams.maxRetries}) after ${retryParams.delayMs}ms...`
           );
           await new Promise((resolve) =>

package/src/utils/IPFSClient.ts

@@ -74,8 +74,8 @@ export interface IPFSClientConfig {
   allowedProtocols?: string[];
 
   /**
-   * SECURITY FIX (MEDIUM-3): Allow localhost URLs
-   * Default: true (required for local IPFS daemon)
+   * Allow localhost URLs (e.g., local IPFS daemon).
+   * Default: false (SSRF protection). Set to true explicitly for local development.
    */
   allowLocalhost?: boolean;
 }
@@ -85,7 +85,8 @@ export interface IPFSClientConfig {
  */
 export const IPFS_CONFIGS = {
   local: {
-    url: 'http://localhost:5001'
+    url: 'http://localhost:5001',
+    allowLocalhost: true, // Explicit opt-in for local development
   },
   infura: {
     url: 'https://ipfs.infura.io:5001/api/v0'
@@ -128,14 +129,14 @@ export class IPFSHTTPClientImpl implements IPFSClient {
     const url = config.url || 'http://localhost:5001';
 
     // SECURITY FIX (MEDIUM-3): Validate URL
-    this.validateUrl(url, config.allowLocalhost ?? true, config.allowedProtocols);
+    this.validateUrl(url, config.allowLocalhost ?? false, config.allowedProtocols);
 
     this.config = {
       url,
       timeout: config.timeout || 60000,
       maxSize: config.maxSize || IPFSHTTPClientImpl.DEFAULT_MAX_SIZE,
       allowedProtocols: config.allowedProtocols || IPFSHTTPClientImpl.DEFAULT_ALLOWED_PROTOCOLS,
-      allowLocalhost: config.allowLocalhost ?? true,
+      allowLocalhost: config.allowLocalhost ?? false,
       auth: config.auth,
       headers: config.headers,
     } as Required<IPFSClientConfig>;
@@ -359,8 +360,9 @@ export function createIPFSClient(): IPFSClient {
     });
   }
 
-  // Default to local IPFS daemon
+  // Default to local IPFS daemon (explicit localhost opt-in)
   return new IPFSHTTPClientImpl({
-    url: 'http://localhost:5001'
+    url: 'http://localhost:5001',
+    allowLocalhost: true,
   });
 }

package/src/utils/computeTypeHash.ts

@@ -44,7 +44,5 @@ if (require.main === module) {
   console.log(typeHash);
   console.log();
 
-  console.log('✅ Update this value in:');
-  console.log('- /Testnet/docs/AIP-4.md:204');
-  console.log('- /Testnet/docs/schemas/aip-4-delivery.eip712.json:11');
+  console.log('Use this type hash in your EIP-712 typed data configuration.');
 }

package/src/utils/retry.ts

@@ -236,7 +236,6 @@ export async function withRetry<T>(
   } = options;
 
   let lastError: unknown;
-  const startTime = Date.now();
 
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {

package/src/utils/validation.ts

@@ -320,7 +320,7 @@ export async function validateEndpointURL(endpoint: string, fieldName: string =
  * @param fieldName - Field name for error messages
  * @throws {InvalidCIDError} If CID is invalid
  */
-export function validateCID(cid: string, fieldName: string = 'cid'): void {
+export function validateCID(cid: string, _fieldName: string = 'cid'): void {
   if (!cid || typeof cid !== 'string') {
     throw new InvalidCIDError(String(cid), 'CID is required');
   }
@@ -337,7 +337,7 @@ export function validateCID(cid: string, fieldName: string = 'cid'): void {
  * @param fieldName - Field name for error messages
  * @throws {InvalidArweaveTxIdError} If TX ID is invalid
  */
-export function validateArweaveTxId(txId: string, fieldName: string = 'txId'): void {
+export function validateArweaveTxId(txId: string, _fieldName: string = 'txId'): void {
   if (!txId || typeof txId !== 'string') {
     throw new InvalidArweaveTxIdError(String(txId), 'TX ID is required');
   }