@agirails/sdk 2.2.3 → 2.3.0

package/src/level0/request.ts

@@ -14,6 +14,7 @@ import { NoProviderFoundError, TimeoutError, ValidationError } from '../errors';
 import { safeJSONParse, validateServiceName, isValidAddress } from '../utils/security';
 import { Logger } from '../utils/Logger';
 import { ethers } from 'ethers';
+import { resolvePrivateKey } from '../wallet/keystore';
 
 /**
  * Request a service
@@ -61,7 +62,6 @@ export async function request(
   service: string,
   options: RequestOptions
 ): Promise<RequestResult> {
-  // SECURITY FIX (H-2): Validate service name to prevent injection
   const validatedService = validateServiceName(service);
 
   const logger = new Logger({ source: 'request' });
@@ -75,12 +75,8 @@ export async function request(
     });
   }
 
-  // SECURITY FIX (RPCURL): Use rpcUrl from options or fallback to network default
-  // This allows Level0 request() to work with testnet/mainnet without requiring
-  // explicit rpcUrl if user is okay with public RPC endpoints.
   let rpcUrl = options.rpcUrl;
   if (!rpcUrl && (options.network === 'testnet' || options.network === 'mainnet')) {
-    // Import getNetwork to get default rpcUrl from network config
     const { getNetwork } = await import('../config/networks');
     const networkName = options.network === 'testnet' ? 'base-sepolia' : 'base-mainnet';
     const networkConfig = getNetwork(networkName);
@@ -88,27 +84,27 @@ export async function request(
     logger.info(`Using default RPC URL for ${networkName}: ${rpcUrl}`);
   }
 
-  // Create ACTP client
+  const resolvedKey = await resolveKeyIfNeeded(options.wallet, options.network, options.stateDirectory);
+  const resolvedAddress = resolvedKey
+    ? new ethers.Wallet(resolvedKey).address.toLowerCase()
+    : undefined;
+
   const client = await ACTPClient.create({
     mode: options.network === 'testnet' ? 'testnet' : options.network === 'mainnet' ? 'mainnet' : 'mock',
-    requesterAddress: getRequesterAddress(options.wallet),
+    requesterAddress: resolvedAddress || getRequesterAddress(options.wallet),
     stateDirectory: options.stateDirectory,
-    privateKey: getPrivateKey(options.wallet),
+    privateKey: resolvedKey || getPrivateKey(options.wallet),
     rpcUrl,
   });
 
-  // Calculate deadline
   const deadline = calculateDeadline(options.deadline, options.timeout);
-
-  // Create transaction with service metadata
   const startTime = Date.now();
 
   try {
-    const requesterAddress = getRequesterAddress(options.wallet);
+    const requesterAddress = resolvedAddress || getRequesterAddress(options.wallet);
     const amountWei = (options.budget * 1_000_000).toString(); // Convert to USDC wei (6 decimals)
 
     // In mock mode, ensure requester has enough funds
-    // This is a convenience feature for testing - won't exist in production
     if (client.runtime && 'mintTokens' in client.runtime) {
       const mockRuntime = client.runtime as any;
       const balance = await mockRuntime.getBalance(requesterAddress);
@@ -122,30 +118,19 @@ export async function request(
       }
     }
 
-    // ARCHITECTURE FIX: Service metadata handling
-    // - MockRuntime: Store plaintext for provider matching and input extraction
-    // - BlockchainRuntime: Hashes plaintext internally before sending on-chain
-    //
-    // Provider needs plaintext to:
-    // 1. Match service name to handler (findServiceHandler)
-    // 2. Extract input data for job execution (extractJobInput)
-    //
-    // On-chain storage uses bytes32 hash (BlockchainRuntime.validateServiceHash handles this)
     const serviceMetadata = JSON.stringify({
       service: validatedService,
       input: options.input,
       timestamp: Date.now(),
     });
 
-    // Create transaction with structured metadata
-    // MockRuntime stores as-is, BlockchainRuntime hashes for on-chain
     const txId = await client.runtime.createTransaction({
       provider,
       requester: requesterAddress,
       amount: amountWei,
       deadline,
-      disputeWindow: options.disputeWindow ?? 172800, // Default 2 days
-      serviceDescription: serviceMetadata, // Structured JSON for provider parsing
+      disputeWindow: options.disputeWindow ?? 172800,
+      serviceDescription: serviceMetadata,
     });
 
     // Call onProgress if provided
@@ -187,12 +172,8 @@ export async function request(
       attempts++;
     }
 
-    // Check if we got a result
     if (!tx || (tx.state !== 'DELIVERED' && tx.state !== 'SETTLED')) {
-      const _timedOut = true; // Flag for potential future use
-
-      // SECURITY FIX (H-3): Auto-cancel transaction on timeout if still in early state
-      // This prevents funds from being locked indefinitely if provider never responds
+      // Auto-cancel on timeout if still in early state
       if (tx && (tx.state === 'INITIATED' || tx.state === 'COMMITTED')) {
         try {
           logger.warn('Transaction timed out, cancelling to release funds', {
@@ -200,8 +181,6 @@ export async function request(
             state: tx.state,
           });
 
-          // ACTUALLY CANCEL THE TRANSACTION
-          // Check if runtime has cancelTransaction method
           if ('cancelTransaction' in client.runtime) {
             await (client.runtime as any).cancelTransaction(txId);
             logger.info('Transaction cancelled successfully', { txId });
@@ -211,7 +190,6 @@ export async function request(
             (error as any).wasCancelled = true;
             throw error;
           } else {
-            // Fallback: Transition to CANCELLED state
             await client.runtime.transitionState(txId, 'CANCELLED');
             logger.info('Transaction cancelled successfully (via transitionState)', { txId });
 
@@ -222,7 +200,6 @@ export async function request(
           }
         } catch (cancelError) {
           logger.error('Failed to cancel timed-out transaction', { txId }, cancelError as Error);
-          // Continue with original timeout error
         }
       }
 
@@ -232,13 +209,8 @@ export async function request(
       throw error;
     }
 
-    // SECURITY FIX (C-3): Safe JSON parsing with schema validation
-    // Extract result from delivery proof
     let deliveredResult: any = {};
     if (tx.deliveryProof) {
-      // Define expected schema for delivery proof
-      // NOTE: 'type' field with value 'delivery.proof' is the unique wrapper marker
-      // (set by ProofGenerator.generateDeliveryProof) that handlers won't naturally return
       const DELIVERY_PROOF_SCHEMA: Record<string, string> = {
         result: 'any',
         data: 'any',
@@ -247,28 +219,18 @@ export async function request(
         timestamp: 'number',
         contentHash: 'string',
         txId: 'string',
-        type: 'string',  // Unique marker: 'delivery.proof'
+        type: 'string',
       };
 
-      // Use safeJSONParse with schema validation which:
-      // 1. Validates JSON structure
-      // 2. Removes __proto__, constructor, prototype properties
-      // 3. Prevents prototype pollution attacks
-      // 4. Validates against expected schema
-      // 5. Checks size limits to prevent DoS
-      // 6. Returns null if parsing fails
       const parsed = safeJSONParse(tx.deliveryProof, DELIVERY_PROOF_SCHEMA);
 
       if (parsed !== null) {
         deliveredResult = parsed;
       } else {
-        // If parsing failed, treat as plain text (but don't execute or eval)
         deliveredResult = { data: tx.deliveryProof };
         logger.warn('Failed to parse delivery proof as JSON', { txId });
       }
     } else if (options.network === 'testnet' || options.network === 'mainnet') {
-      // KNOWN LIMITATION: BlockchainRuntime doesn't fetch deliveryProof from IPFS yet
-      // Result will be empty until this is implemented
       logger.warn(
         'Delivery proof retrieval not yet implemented for testnet/mainnet. ' +
         'Result may be empty. Use ACTPClient with manual proof handling for production.',
@@ -276,17 +238,11 @@ export async function request(
       );
     }
 
-    // SECURITY FIX (CRITICAL-2): Release escrow only after proper validation
-    // For mock mode, auto-release is safe. For testnet/mainnet, require attestation.
     if (tx.state === 'DELIVERED' && tx.escrowId) {
-      // Wait for dispute window to expire
       const disputeWindowEnd = (tx.completedAt ?? 0) + tx.disputeWindow;
       const currentTime = client.runtime.time.now();
 
       if (currentTime >= disputeWindowEnd) {
-        // SECURITY FIX (CRITICAL-2): Only auto-release in mock mode
-        // For real networks, the requester should manually verify and release
-        // or use attestation-based verification
         const isMockMode = options.network !== 'testnet' && options.network !== 'mainnet';
 
         if (isMockMode) {
@@ -353,6 +309,20 @@ export async function request(
   }
 }
 
+/**
+ * Resolve private key from keystore if wallet is auto/undefined and network is testnet/mainnet.
+ * Returns undefined if wallet is explicitly set (caller should use getPrivateKey instead).
+ */
+async function resolveKeyIfNeeded(
+  wallet?: 'auto' | 'connect' | string | { privateKey: string },
+  network?: string,
+  stateDirectory?: string
+): Promise<string | undefined> {
+  if (wallet && wallet !== 'auto') return undefined; // explicit wallet, skip auto-detect
+  if (network !== 'testnet' && network !== 'mainnet') return undefined;
+  return resolvePrivateKey(stateDirectory);
+}
+
 /**
  * Find provider for service
  *
@@ -381,23 +351,10 @@ function findProvider(
   return providers[0];
 }
 
-/**
- * Get requester address from wallet option
- *
- * SECURITY FIX (HIGH): Properly derive addresses from private keys using ethers
- * Never fabricate addresses or use partial key slices as addresses.
- *
- * @param wallet - Wallet configuration
- * @returns Ethereum address
- * @throws {ValidationError} If address format is invalid
- */
 function getRequesterAddress(
   wallet?: 'auto' | 'connect' | string | { privateKey: string }
 ): string {
-  // For mock mode only: generate deterministic address
-  // This is only safe because mock mode doesn't involve real funds
   if (!wallet || wallet === 'auto') {
-    // Create a valid Ethereum address (40 hex chars) - ONLY for mock mode
     const hex = Buffer.from('requester').toString('hex');
     return '0x' + hex.padEnd(40, '0');
   }
@@ -407,15 +364,12 @@ function getRequesterAddress(
   }
 
   if (typeof wallet === 'string') {
-    // SECURITY FIX (HIGH): Validate address format
     if (!isValidAddress(wallet)) {
       throw new ValidationError('wallet', `Invalid Ethereum address format: ${wallet}`);
     }
     return wallet.toLowerCase();
   }
 
-  // SECURITY FIX (HIGH): Derive address from private key using ethers
-  // This is the correct way to get address from a private key
   try {
     const walletInstance = new ethers.Wallet(wallet.privateKey);
     return walletInstance.address.toLowerCase();
@@ -424,15 +378,6 @@ function getRequesterAddress(
   }
 }
 
-/**
- * Get private key from wallet option
- *
- * SECURITY FIX (HIGH): Validate private key format before use
- *
- * @param wallet - Wallet configuration
- * @returns Private key or undefined
- * @throws {ValidationError} If private key format is invalid
- */
 function getPrivateKey(
   wallet?: 'auto' | 'connect' | string | { privateKey: string }
 ): string | undefined {
@@ -440,12 +385,8 @@ function getPrivateKey(
     return undefined;
   }
 
-  // If wallet is a string that looks like a private key (0x + 64 hex chars), use it
-  // Otherwise treat it as an address and return undefined
   if (typeof wallet === 'string') {
-    // Check if it looks like a private key (0x + 64 hex chars)
     if (/^0x[0-9a-fA-F]{64}$/.test(wallet)) {
-      // Validate by trying to create a wallet
       try {
         new ethers.Wallet(wallet);
         return wallet;
@@ -453,11 +394,9 @@ function getPrivateKey(
         throw new ValidationError('wallet', 'Invalid private key format');
       }
     }
-    // It's an address, not a private key
     return undefined;
   }
 
-  // Validate private key format
   if (wallet.privateKey) {
     try {
       new ethers.Wallet(wallet.privateKey);

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/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
 // ============================================================================