@agirails/sdk 2.5.3 → 2.5.4

package/src/types/adapter.ts

@@ -1,310 +0,0 @@
-/**
- * Adapter types for the ACTP SDK adapter routing system.
- *
- * This module defines types and Zod schemas for:
- * - AdapterMetadata: Capabilities and configuration for each adapter
- * - PaymentMetadata: Request-level hints for adapter selection
- * - UnifiedPayParams: Common payment parameters across adapters
- * - UnifiedPayResult: Common result type for all adapters
- *
- * @module types/adapter
- */
-
-import { z } from 'zod';
-import type { X402FeeBreakdown } from './x402';
-
-// ============================================================================
-// AdapterMetadata - Describes adapter capabilities
-// ============================================================================
-
-/**
- * Metadata describing an adapter's capabilities.
- *
- * CRITICAL: All adapters must respect ACTP state machine:
- * - No skipping IN_PROGRESS state
- * - DELIVERED requires proof
- * - releaseEscrow must be called explicitly (NO auto-settle)
- */
-export interface AdapterMetadata {
-  /** Unique adapter identifier */
-  id: string;
-
-  /** Human-readable name */
-  name: string;
-
-  /** Whether adapter uses escrow */
-  usesEscrow: boolean;
-
-  /** Whether adapter supports dispute resolution */
-  supportsDisputes: boolean;
-
-  /** Whether adapter requires on-chain identity */
-  requiresIdentity: boolean;
-
-  /** Supported identity types (erc8004, did, ens) */
-  supportedIdentityTypes?: string[];
-
-  /**
-   * Settlement mode:
-   * - 'explicit': caller must call releaseEscrow (REQUIRED for ACTP compliance)
-   * - 'timed': auto-release after dispute window (future, not Phase 1)
-   * - 'atomic': instant settlement, no escrow (x402 protocol)
-   */
-  settlementMode: 'explicit' | 'timed' | 'atomic';
-
-  /** Priority for auto-selection (higher = preferred) */
-  priority: number;
-}
-
-/**
- * Zod schema for AdapterMetadata runtime validation.
- */
-export const AdapterMetadataSchema = z.object({
-  id: z.string().min(1),
-  name: z.string().min(1),
-  usesEscrow: z.boolean(),
-  supportsDisputes: z.boolean(),
-  requiresIdentity: z.boolean(),
-  supportedIdentityTypes: z.array(z.string()).optional(),
-  settlementMode: z.enum(['explicit', 'timed', 'atomic']),
-  priority: z.number().int().min(0).max(100),
-});
-
-// ============================================================================
-// PaymentMetadata - Request-level hints for adapter selection
-// ============================================================================
-
-/**
- * Identity information for adapter selection.
- */
-export interface PaymentIdentity {
-  type: 'erc8004' | 'did' | 'ens' | 'address';
-  value: string;
-}
-
-/**
- * Payment request metadata for adapter selection.
- */
-export interface PaymentMetadata {
-  /** Explicitly request specific adapter */
-  preferredAdapter?: string;
-
-  /** Require escrow protection */
-  requiresEscrow?: boolean;
-
-  /** Require dispute resolution capability */
-  requiresDispute?: boolean;
-
-  /** Identity information */
-  identity?: PaymentIdentity;
-
-  /** x402 specific: payment method hint */
-  paymentMethod?: 'x402' | 'actp' | 'auto';
-}
-
-/**
- * Zod schema for PaymentIdentity runtime validation.
- */
-export const PaymentIdentitySchema = z.object({
-  type: z.enum(['erc8004', 'did', 'ens', 'address']),
-  value: z.string().min(1),
-});
-
-/**
- * Zod schema for PaymentMetadata runtime validation.
- */
-export const PaymentMetadataSchema = z.object({
-  preferredAdapter: z.string().optional(),
-  requiresEscrow: z.boolean().optional(),
-  requiresDispute: z.boolean().optional(),
-  identity: PaymentIdentitySchema.optional(),
-  paymentMethod: z.enum(['x402', 'actp', 'auto']).optional(),
-});
-
-// ============================================================================
-// UnifiedPayParams - Common payment parameters
-// ============================================================================
-
-/**
- * Unified payment parameters accepted by all adapters.
- */
-export interface UnifiedPayParams {
-  /** Recipient - address, HTTP endpoint, or ERC-8004 agent ID */
-  to: string;
-
-  /** Amount in human-readable format */
-  amount: string | number;
-
-  /** Deadline (relative like '+24h' or unix timestamp) */
-  deadline?: string | number;
-
-  /** Dispute window in seconds (min 3600, max 30 days) */
-  disputeWindow?: number;
-
-  /** Service description */
-  description?: string;
-
-  /** Adapter selection metadata */
-  metadata?: PaymentMetadata;
-
-  /**
-   * ERC-8004 agent ID (populated when 'to' was resolved from agentId).
-   * Set by AdapterRouter when resolving agent ID to wallet address.
-   * Used for reputation reporting after settlement.
-   */
-  erc8004AgentId?: string;
-}
-
-/**
- * Minimum dispute window in seconds (1 hour).
- * Ensures requesters have reasonable time to dispute.
- */
-const MIN_DISPUTE_WINDOW = 3600;
-
-/**
- * Maximum dispute window in seconds (30 days).
- * Prevents excessively long fund locks.
- */
-const MAX_DISPUTE_WINDOW = 30 * 24 * 3600;
-
-/**
- * Zod schema for UnifiedPayParams with strict validation.
- */
-export const UnifiedPayParamsSchema = z.object({
-  to: z.string().min(1),
-  amount: z.union([z.string().min(1), z.number().positive()]),
-  deadline: z.union([z.string(), z.number()]).optional(),
-  disputeWindow: z
-    .number()
-    .int()
-    .min(MIN_DISPUTE_WINDOW)
-    .max(MAX_DISPUTE_WINDOW)
-    .optional(),
-  description: z.string().optional(),
-  metadata: PaymentMetadataSchema.optional(),
-  erc8004AgentId: z.string().optional(),
-});
-
-// ============================================================================
-// UnifiedPayResult - Common result type
-// ============================================================================
-
-/**
- * Transaction state after payment initiation.
- *
- * Note: 'COMMITTED' means funds are locked but work hasn't started.
- * 'IN_PROGRESS' means provider has acknowledged and started work.
- */
-export type InitialTransactionState = 'COMMITTED' | 'IN_PROGRESS';
-
-/**
- * Unified payment result returned by all adapters.
- *
- * NOTE: success=true means payment INITIATED, not settled.
- * Caller must call releaseEscrow() after delivery verification.
- */
-export interface UnifiedPayResult {
-  /** ACTP transaction ID */
-  txId: string;
-
-  /** Escrow ID (for release) - null for non-escrow adapters */
-  escrowId: string | null;
-
-  /** Adapter that handled the payment */
-  adapter: string;
-
-  /** Current state (COMMITTED, not SETTLED) */
-  state: InitialTransactionState;
-
-  /** Whether payment initiation succeeded */
-  success: boolean;
-
-  /** Amount locked (formatted) */
-  amount: string;
-
-  /** For x402: the HTTP response */
-  response?: Response;
-
-  /** Error message if failed */
-  error?: string;
-
-  /**
-   * IMPORTANT: Payment is NOT complete until you call:
-   * await client.release(result.escrowId)
-   *
-   * Always true for ACTP-compliant adapters.
-   */
-  releaseRequired: boolean;
-
-  /** Provider address (normalized to lowercase) */
-  provider: string;
-
-  /** Requester address (normalized to lowercase) */
-  requester: string;
-
-  /** Deadline as ISO 8601 timestamp */
-  deadline: string;
-
-  /**
-   * ERC-8004 agent ID (if transaction involved ERC-8004 agent).
-   * 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;
-}
-
-/**
- * Zod schema for UnifiedPayResult validation.
- */
-export const UnifiedPayResultSchema = z.object({
-  txId: z.string().min(1),
-  escrowId: z.string().nullable(),
-  adapter: z.string().min(1),
-  state: z.enum(['COMMITTED', 'IN_PROGRESS']),
-  success: z.boolean(),
-  amount: z.string().min(1),
-  response: z.any().optional(),
-  error: z.string().optional(),
-  releaseRequired: z.boolean(),
-  provider: z.string().min(1),
-  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(),
-});
-
-// ============================================================================
-// Validation Helpers
-// ============================================================================
-
-/**
- * Validates UnifiedPayParams at runtime.
- *
- * @param params - Parameters to validate
- * @returns Validated params
- * @throws {z.ZodError} If validation fails
- */
-export function validatePayParams(params: unknown): UnifiedPayParams {
-  return UnifiedPayParamsSchema.parse(params);
-}
-
-/**
- * Safe parse for UnifiedPayParams (doesn't throw).
- *
- * @param params - Parameters to validate
- * @returns Result with success flag and data or error
- */
-export function safeValidatePayParams(params: unknown): z.SafeParseReturnType<unknown, UnifiedPayParams> {
-  return UnifiedPayParamsSchema.safeParse(params);
-}

package/src/types/agent.ts

@@ -1,79 +0,0 @@
-/**
- * Agent Registry Types (AIP-7)
- *
- * Types for AI agent identity, registration, and reputation
- */
-
-/**
- * Service descriptor metadata for an agent
- */
-export interface ServiceDescriptor {
-  /** keccak256(lowercase(serviceType)) */
-  serviceTypeHash: string;
-  /** Human-readable service type (lowercase, alphanumeric + hyphens) */
-  serviceType: string;
-  /** IPFS/HTTPS URL to JSON Schema for inputData */
-  schemaURI: string;
-  /** Minimum price in USDC base units (6 decimals) */
-  minPrice: bigint;
-  /** Maximum price in USDC base units */
-  maxPrice: bigint;
-  /** Average completion time in seconds */
-  avgCompletionTime: number;
-  /** IPFS CID to full service descriptor JSON */
-  metadataCID: string;
-}
-
-/**
- * Agent profile stored on-chain
- */
-export interface AgentProfile {
-  /** Agent's Ethereum address (controller of DID) */
-  agentAddress: string;
-  /** Full DID (e.g., did:ethr:8453:0x...) */
-  did: string;
-  /** HTTPS endpoint or IPFS gateway URL */
-  endpoint: string;
-  /** Supported service type hashes */
-  serviceTypes: string[];
-  /** USDC staked (V1: always 0, V2: slashing for disputes) */
-  stakedAmount: bigint;
-  /** Aggregated reputation (scale: 0-10000, 2 decimals precision) */
-  reputationScore: number;
-  /** Count of completed SETTLED transactions */
-  totalTransactions: number;
-  /** Count of transactions that went to DISPUTED state */
-  disputedTransactions: number;
-  /** Cumulative transaction volume (6 decimals) */
-  totalVolumeUSDC: bigint;
-  /** Block timestamp of registration */
-  registeredAt: number;
-  /** Last profile update timestamp */
-  updatedAt: number;
-  /** Agent is accepting new requests */
-  isActive: boolean;
-}
-
-/**
- * Parameters for registering a new agent
- */
-export interface RegisterAgentParams {
-  /** HTTPS endpoint or IPFS gateway URL */
-  endpoint: string;
-  /** List of services the agent provides */
-  serviceDescriptors: ServiceDescriptor[];
-}
-
-/**
- * Query parameters for finding agents by service
- */
-export interface QueryAgentsParams {
-  /** Service type hash to search for */
-  serviceTypeHash: string;
-  /** Minimum reputation score (0-10000) */
-  minReputation?: number;
-  /** Skip first N results (for pagination) */
-  offset?: number;
-  /** Maximum number of results to return */
-  limit?: number;
-}

package/src/types/did.ts

@@ -1,223 +0,0 @@
-/**
- * DID (Decentralized Identity) Types - AIP-7 §2
- *
- * Implements W3C DID specification for Ethereum-based identities
- * using the did:ethr method with ERC-1056 registry
- */
-
-/**
- * DID format: did:ethr:<chainId>:<address>
- * Example: did:ethr:84532:0x742d35cc6634c0532925a3b844bc9e7595f0beb
- */
-export type DID = string;
-
-/**
- * W3C DID Document structure
- * @see https://www.w3.org/TR/did-core/
- */
-export interface DIDDocument {
-  '@context': string | string[];
-  id: DID;
-  verificationMethod?: VerificationMethod[];
-  authentication?: (string | VerificationMethod)[];
-  assertionMethod?: (string | VerificationMethod)[];
-  keyAgreement?: (string | VerificationMethod)[];
-  capabilityInvocation?: (string | VerificationMethod)[];
-  capabilityDelegation?: (string | VerificationMethod)[];
-  service?: ServiceEndpoint[];
-}
-
-/**
- * Verification method for cryptographic key
- */
-export interface VerificationMethod {
-  id: string;
-  type: string;
-  controller: DID;
-  blockchainAccountId?: string; // CAIP-10 format: address@eip155:chainId
-  publicKeyHex?: string;
-  publicKeyBase58?: string;
-  publicKeyMultibase?: string;
-  ethereumAddress?: string;
-  validTo?: number | bigint; // Unix timestamp for delegate validity (ERC-1056)
-}
-
-/**
- * Service endpoint in DID Document
- */
-export interface ServiceEndpoint {
-  id: string;
-  type: string;
-  serviceEndpoint: string | string[] | Record<string, unknown>;
-  description?: string;
-}
-
-/**
- * DID Resolution result
- */
-export interface DIDResolutionResult {
-  didDocument: DIDDocument | null;
-  didResolutionMetadata: DIDResolutionMetadata;
-  didDocumentMetadata: DIDDocumentMetadata;
-}
-
-/**
- * DID Resolution metadata
- */
-export interface DIDResolutionMetadata {
-  contentType?: string;
-  error?: 'invalidDid' | 'notFound' | 'representationNotSupported' | 'unsupportedDidMethod' | string;
-  message?: string;
-}
-
-/**
- * DID Document metadata
- */
-export interface DIDDocumentMetadata {
-  created?: string;
-  updated?: string;
-  deactivated?: boolean;
-  versionId?: string;
-  nextUpdate?: string;
-  nextVersionId?: string;
-}
-
-/**
- * Configuration for DID Resolver
- */
-export interface DIDResolverConfig {
-  /**
-   * Network to use (base-sepolia or base-mainnet)
-   */
-  network?: string;
-
-  /**
-   * Custom RPC URL (overrides network default)
-   */
-  rpcUrl?: string;
-
-  /**
-   * Custom Identity Registry address (overrides network default)
-   */
-  registryAddress?: string;
-
-  /**
-   * Chain ID (required if not using predefined network)
-   */
-  chainId?: number;
-}
-
-/**
- * Parsed DID components
- */
-export interface ParsedDID {
-  method: string; // Always 'ethr' for AGIRAILS
-  chainId: number;
-  address: string; // Lowercase checksummed address
-}
-
-/**
- * ERC-1056 Identity Changed Event
- */
-export interface DIDOwnerChangedEvent {
-  identity: string;
-  owner: string;
-  previousChange: bigint;
-}
-
-/**
- * ERC-1056 Delegate Changed Event
- */
-export interface DIDDelegateChangedEvent {
-  identity: string;
-  delegateType: string; // bytes32 as hex string
-  delegate: string;
-  validTo: bigint;
-  previousChange: bigint;
-}
-
-/**
- * ERC-1056 Attribute Changed Event
- */
-export interface DIDAttributeChangedEvent {
-  identity: string;
-  name: string; // bytes32 as hex string
-  value: Uint8Array;
-  validTo: bigint;
-  previousChange: bigint;
-}
-
-/**
- * Delegate types for ERC-1056
- */
-export enum DelegateType {
-  /** Can sign on behalf of identity */
-  SIGNING = 'veriKey',
-
-  /** Can encrypt messages for identity */
-  ENCRYPTION = 'encryptionKey',
-
-  /** Can perform general actions */
-  GENERAL = 'delegate',
-
-  /** Custom delegate type */
-  CUSTOM = 'custom'
-}
-
-/**
- * Attribute names for ERC-1056
- */
-export enum AttributeName {
-  /** Service endpoint (e.g., AGIRAILS API endpoint) */
-  SERVICE_ENDPOINT = 'did/svc/AGIRAILSProvider',
-
-  /** Public key for verification */
-  PUBLIC_KEY = 'did/pub/Secp256k1/veriKey',
-
-  /** Encryption public key */
-  ENCRYPTION_KEY = 'did/pub/X25519/enc',
-
-  /** Custom attribute */
-  CUSTOM = 'custom'
-}
-
-/**
- * Options for DID signature verification
- */
-export interface VerifySignatureOptions {
-  /** Chain ID to verify against (prevents cross-chain replay) */
-  chainId: number;
-
-  /** Expected DID (optional additional check) */
-  expectedDID?: DID;
-
-  /** Timestamp for delegate validity check */
-  timestamp?: number;
-
-  /**
-   * Use domain separation to prevent cross-protocol replay attacks
-   * Default: true (recommended for security)
-   * Set to false only for backwards compatibility with old signatures
-   */
-  useDomainSeparation?: boolean;
-}
-
-/**
- * Result of signature verification
- */
-export interface SignatureVerificationResult {
-  /** Whether signature is valid */
-  valid: boolean;
-
-  /** Recovered signer address */
-  signer?: string;
-
-  /** Error message if verification failed */
-  error?: string;
-
-  /** Whether signer is a delegate (not the owner) */
-  isDelegate?: boolean;
-
-  /** Delegate type if signer is a delegate */
-  delegateType?: string;
-}