@agirails/sdk 2.0.0-beta

package/src/types/message.ts

@@ -0,0 +1,145 @@
+/**
+ * ACTP Message Types
+ * Reference: Yellow Paper §4-10 (AIPs)
+ */
+
+/**
+ * Base ACTP message structure
+ */
+export interface ACTPMessage {
+  type: string;
+  version: string;
+  from: string; // DID
+  to: string; // DID
+  timestamp: number;
+  nonce: string;
+  signature?: string;
+  [key: string]: any;
+}
+
+/**
+ * Quote Request (AIP-2)
+ * Reference: Yellow Paper §6.2.1
+ */
+export interface QuoteRequest extends ACTPMessage {
+  type: 'quote.request';
+  serviceRequest: {
+    capabilityType: string;
+    parameters: Record<string, any>;
+    deliveryRequirements: {
+      deadline: string;
+      maxDeliveryTime: string;
+    };
+  };
+  budgetConstraints: {
+    maxPrice: string;
+    currency: 'USDC';
+  };
+  expiresAt: string;
+}
+
+/**
+ * Quote Response (AIP-2)
+ * Reference: Yellow Paper §6.2.2
+ */
+export interface QuoteResponse extends ACTPMessage {
+  type: 'quote.response';
+  inResponseTo: string;
+  quoteId: string;
+  pricing: {
+    totalPrice: string;
+    currency: 'USDC';
+    breakdown: Array<{ item: string; amount: string }>;
+    platformFee: string;
+  };
+  sla: {
+    successRateGuarantee: number;
+    refundPolicy: string;
+  };
+  expiresAt: string;
+}
+
+/**
+ * Delivery Proof (AIP-4) - DEPRECATED
+ * @deprecated Use DeliveryProofMessage instead (AIP-4 v1.1)
+ */
+export interface DeliveryProof {
+  type: 'delivery.proof';
+  txId: string;
+  contentHash: string;
+  timestamp: number;
+  deliveryUrl?: string;
+  metadata: {
+    size: number;
+    mimeType: string;
+    [key: string]: any;
+  };
+}
+
+/**
+ * Delivery Proof Message (AIP-4 v1.1)
+ * Reference: AIP-4 §3.2, §8.1
+ * Complete schema for delivery proofs with EAS attestations
+ */
+export interface DeliveryProofMessage {
+  type: 'agirails.delivery.v1';
+  version: string; // Semantic version (e.g., "1.0.0")
+  txId: string; // bytes32 (0x-prefixed)
+  provider: string; // DID (e.g., "did:ethr:84532:0x...")
+  consumer: string; // DID
+  resultCID: string; // IPFS CID (CIDv1, base32, e.g., "bafybeig...")
+  resultHash: string; // Keccak256 hash of canonical result JSON
+  metadata?: {
+    executionTime?: number; // Seconds
+    outputFormat?: string; // MIME type
+    outputSize?: number; // Bytes
+    notes?: string; // Max 500 chars
+  };
+  easAttestationUID: string; // bytes32 (0x-prefixed)
+  deliveredAt: number; // Unix timestamp (seconds)
+  chainId: number; // 84532 (Base Sepolia) or 8453 (Base Mainnet)
+  nonce: number; // Monotonically increasing
+  signature: string; // EIP-712 signature (0x-prefixed, 130 chars)
+}
+
+/**
+ * EAS Attestation Data for delivery proofs
+ */
+export interface EASAttestationData {
+  schema: string; // EAS schema UID
+  recipient: string; // Provider address
+  expirationTime: number; // Unix timestamp (0 for no expiration)
+  revocable: boolean;
+  refUID: string; // Reference to transaction
+  data: string; // ABI-encoded attestation data
+}
+
+/**
+ * Quote Message (AIP-2 v1.0)
+ * Reference: AIP-2 §2.1, §2.2
+ * Price quote submitted by provider for negotiated transactions
+ */
+export interface QuoteMessageV2 {
+  type: 'agirails.quote.v1';
+  version: '1.0.0';
+  txId: string; // bytes32 (0x-prefixed)
+  provider: string; // DID (e.g., "did:ethr:84532:0x...")
+  consumer: string; // DID
+  quotedAmount: string; // Provider's quoted price (base units, string to avoid JS overflow)
+  originalAmount: string; // Consumer's original offer from AIP-1
+  maxPrice: string; // Consumer's maximum acceptable price from AIP-1
+  currency: string; // Currently "USDC" only
+  decimals: number; // Token decimals (6 for USDC)
+  quotedAt: number; // Unix timestamp (seconds)
+  expiresAt: number; // Unix timestamp (seconds)
+  justification?: {
+    reason?: string;
+    estimatedTime?: number;
+    computeCost?: number;
+    breakdown?: Record<string, any>;
+  };
+  chainId: number; // 84532 (Base Sepolia) or 8453 (Base Mainnet)
+  nonce: number; // Monotonically increasing per provider + message type
+  signature: string; // EIP-712 signature (0x-prefixed, 130 chars)
+}
+

package/src/types/state.ts

@@ -0,0 +1,77 @@
+/**
+ * ACTP State Machine
+ * Reference: Yellow Paper §3.2
+ */
+
+export enum State {
+  INITIATED = 0,
+  QUOTED = 1,
+  COMMITTED = 2,
+  IN_PROGRESS = 3,
+  DELIVERED = 4,
+  SETTLED = 5,
+  DISPUTED = 6,
+  CANCELLED = 7
+}
+
+export class StateMachine {
+  /**
+   * Valid state transitions per Yellow Paper §3.2.2
+   */
+  private static readonly TRANSITIONS: Record<State, State[]> = {
+    [State.INITIATED]: [State.QUOTED, State.COMMITTED, State.CANCELLED], // Allow direct INITIATED → COMMITTED (AIP-3)
+    [State.QUOTED]: [State.COMMITTED, State.CANCELLED],
+    [State.COMMITTED]: [State.IN_PROGRESS, State.CANCELLED],
+    [State.IN_PROGRESS]: [State.DELIVERED, State.DISPUTED],
+    [State.DELIVERED]: [State.SETTLED, State.DISPUTED],
+    [State.DISPUTED]: [State.SETTLED, State.CANCELLED],
+    [State.SETTLED]: [], // Terminal state
+    [State.CANCELLED]: [] // Terminal state
+  };
+
+  /**
+   * Check if state transition is valid
+   */
+  static isValidTransition(from: State, to: State): boolean {
+    return this.TRANSITIONS[from]?.includes(to) ?? false;
+  }
+
+  /**
+   * Check if state is terminal (no further transitions)
+   */
+  static isTerminalState(state: State): boolean {
+    return state === State.SETTLED || state === State.CANCELLED;
+  }
+
+  /**
+   * Get human-readable state name
+   */
+  static getStateName(state: State): string {
+    return State[state];
+  }
+
+  /**
+   * Get all valid next states from current state
+   */
+  static getNextValidStates(currentState: State): State[] {
+    return this.TRANSITIONS[currentState] || [];
+  }
+
+  /**
+   * Validate state transition or throw error
+   */
+  static validateTransition(from: State, to: State): void {
+    if (!this.isValidTransition(from, to)) {
+      const validStates = this.getNextValidStates(from)
+        .map(s => State[s])
+        .join(', ');
+
+      throw new Error(
+        `Invalid state transition: ${State[from]} → ${State[to]}. ` +
+        `Valid transitions from ${State[from]}: ${validStates || 'none (terminal state)'}`
+      );
+    }
+  }
+}
+
+

package/src/types/transaction.ts

@@ -0,0 +1,54 @@
+import { State } from './state';
+
+/**
+ * ACTP Transaction
+ * Reference: Yellow Paper §3.1
+ */
+export interface Transaction {
+  txId: string;
+  requester: string;
+  provider: string;
+  amount: bigint;
+  state: State;
+  createdAt: number;
+  deadline: number;
+  disputeWindow: number;
+  escrowContract: string;
+  escrowId: string;
+  metadata: string;
+}
+
+/**
+ * Parameters for creating a new transaction
+ */
+export interface CreateTransactionParams {
+  provider: string;
+  requester: string;
+  amount: bigint;
+  deadline: number;
+  disputeWindow: number;
+  metadata?: string;
+}
+
+/**
+ * Dispute resolution split
+ */
+export interface DisputeResolution {
+  requesterAmount: bigint;
+  providerAmount: bigint;
+  mediatorAmount: bigint;
+  mediator?: string;
+}
+
+/**
+ * Economic parameters (fee structure)
+ */
+export interface EconomicParams {
+  baseFeeNumerator: number;
+  baseFeeDenominator: number;
+  feeRecipient: string;
+  requesterPenaltyBps: number;
+  providerPenaltyBps: number;
+}
+
+

package/src/utils/IPFSClient.ts

@@ -0,0 +1,248 @@
+/**
+ * IPFS Client Implementation
+ * Wrapper around kubo-rpc-client (formerly ipfs-http-client) for AIP-4 delivery proof uploads
+ */
+
+import { create, IPFSHTTPClient, Options } from 'kubo-rpc-client';
+
+/**
+ * IPFS Client Interface (from DeliveryProofBuilder)
+ */
+export interface IPFSClient {
+  /**
+   * Upload data to IPFS
+   * @param data - JSON string or buffer
+   * @returns CIDv1 string (base32, e.g., "bafybeig...")
+   */
+  add(data: string | Buffer): Promise<string>;
+
+  /**
+   * Pin content to prevent garbage collection
+   * @param cid - IPFS CID
+   */
+  pin(cid: string): Promise<void>;
+
+  /**
+   * Retrieve content from IPFS
+   * @param cid - IPFS CID
+   * @returns Content as string
+   */
+  get(cid: string): Promise<string>;
+}
+
+/**
+ * IPFS Client Configuration
+ */
+export interface IPFSClientConfig {
+  /**
+   * IPFS HTTP API endpoint
+   * Default: http://localhost:5001 (local IPFS daemon)
+   * Production: https://ipfs.infura.io:5001/api/v0 (Infura)
+   */
+  url?: string;
+
+  /**
+   * API authentication (for Infura, Pinata, etc.)
+   */
+  auth?: {
+    username: string;
+    password: string;
+  };
+
+  /**
+   * HTTP headers (for API keys)
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Request timeout (ms)
+   * Default: 60000 (60 seconds)
+   */
+  timeout?: number;
+}
+
+/**
+ * Default IPFS configurations
+ */
+export const IPFS_CONFIGS = {
+  local: {
+    url: 'http://localhost:5001'
+  },
+  infura: {
+    url: 'https://ipfs.infura.io:5001/api/v0'
+    // Auth required: Set INFURA_PROJECT_ID and INFURA_PROJECT_SECRET
+  },
+  pinata: {
+    url: 'https://api.pinata.cloud'
+    // Headers required: Set pinata_api_key and pinata_secret_api_key
+  }
+};
+
+/**
+ * IPFS HTTP Client Implementation
+ * Uses ipfs-http-client library
+ */
+export class IPFSHTTPClientImpl implements IPFSClient {
+  private client: IPFSHTTPClient;
+  private config: IPFSClientConfig;
+
+  /**
+   * Create IPFS client
+   * @param config - IPFS client configuration
+   */
+  constructor(config: IPFSClientConfig = {}) {
+    this.config = {
+      url: config.url || 'http://localhost:5001',
+      timeout: config.timeout || 60000,
+      ...config
+    };
+
+    const options: Options = {
+      url: this.config.url,
+      timeout: this.config.timeout
+    };
+
+    // Add authentication if provided
+    if (this.config.auth) {
+      options.headers = {
+        ...this.config.headers,
+        authorization: 'Basic ' + Buffer.from(
+          `${this.config.auth.username}:${this.config.auth.password}`
+        ).toString('base64')
+      };
+    } else if (this.config.headers) {
+      options.headers = this.config.headers;
+    }
+
+    this.client = create(options);
+  }
+
+  /**
+   * Upload data to IPFS
+   * @param data - JSON string or buffer
+   * @returns CIDv1 string (base32)
+   */
+  async add(data: string | Buffer): Promise<string> {
+    try {
+      const content = typeof data === 'string' ? Buffer.from(data, 'utf-8') : data;
+
+      const result = await this.client.add(content, {
+        cidVersion: 1, // Use CIDv1 (base32)
+        hashAlg: 'sha2-256',
+        pin: true // Auto-pin on upload
+      });
+
+      // Convert CID to base32 string (e.g., "bafybeig...")
+      return result.cid.toString();
+    } catch (error) {
+      throw new Error(`IPFS upload failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Pin content to prevent garbage collection
+   * @param cid - IPFS CID
+   */
+  async pin(cid: string): Promise<void> {
+    try {
+      await this.client.pin.add(cid);
+    } catch (error) {
+      throw new Error(`IPFS pin failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Retrieve content from IPFS
+   * @param cid - IPFS CID
+   * @returns Content as string
+   */
+  async get(cid: string): Promise<string> {
+    try {
+      const chunks: Uint8Array[] = [];
+
+      for await (const chunk of this.client.cat(cid)) {
+        chunks.push(chunk);
+      }
+
+      // Concatenate all chunks
+      const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+      const result = new Uint8Array(totalLength);
+      let offset = 0;
+
+      for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+      }
+
+      return Buffer.from(result).toString('utf-8');
+    } catch (error) {
+      throw new Error(`IPFS retrieval failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Check if IPFS daemon is reachable
+   * @returns true if connected, false otherwise
+   */
+  async isOnline(): Promise<boolean> {
+    try {
+      await this.client.id();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get IPFS node ID
+   * @returns IPFS node ID
+   */
+  async getNodeId(): Promise<string> {
+    try {
+      const id = await this.client.id();
+      return id.id.toString();
+    } catch (error) {
+      throw new Error(`Failed to get node ID: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+
+/**
+ * Create IPFS client with environment-based configuration
+ * Checks for IPFS_URL, INFURA_PROJECT_ID, PINATA_API_KEY env vars
+ */
+export function createIPFSClient(): IPFSClient {
+  // Check for Infura credentials
+  if (process.env.INFURA_PROJECT_ID && process.env.INFURA_PROJECT_SECRET) {
+    return new IPFSHTTPClientImpl({
+      url: 'https://ipfs.infura.io:5001/api/v0',
+      auth: {
+        username: process.env.INFURA_PROJECT_ID,
+        password: process.env.INFURA_PROJECT_SECRET
+      }
+    });
+  }
+
+  // Check for Pinata credentials
+  if (process.env.PINATA_API_KEY && process.env.PINATA_SECRET_API_KEY) {
+    return new IPFSHTTPClientImpl({
+      url: 'https://api.pinata.cloud',
+      headers: {
+        pinata_api_key: process.env.PINATA_API_KEY,
+        pinata_secret_api_key: process.env.PINATA_SECRET_API_KEY
+      }
+    });
+  }
+
+  // Check for custom IPFS URL
+  if (process.env.IPFS_URL) {
+    return new IPFSHTTPClientImpl({
+      url: process.env.IPFS_URL
+    });
+  }
+
+  // Default to local IPFS daemon
+  return new IPFSHTTPClientImpl({
+    url: 'http://localhost:5001'
+  });
+}