@agirails/sdk 2.0.0-beta

package/src/protocol/MessageSigner.ts

@@ -0,0 +1,336 @@
+import { Signer, ethers, AbiCoder } from 'ethers';
+import { ACTPMessage, DeliveryProof } from '../types';
+import { SignatureVerificationError } from '../errors';
+import {
+  EIP712Domain,
+  getMessageTypes,
+  QuoteRequestData,
+  QuoteResponseData,
+  DeliveryProofData,
+  deliveryProofDataFromProof
+} from '../types/eip712';
+import { IReceivedNonceTracker } from '../utils/ReceivedNonceTracker';
+
+// Legacy generic ACTP message types moved to types/eip712.ts
+
+/**
+ * TypeScript interface for ethers v6 Signer with signTypedData method
+ *
+ * Note: ethers v6 uses signTypedData() (without underscore), not _signTypedData().
+ * This interface properly types the method for v6 compatibility.
+ */
+interface SignerWithTypedData extends Signer {
+  signTypedData(
+    domain: EIP712Domain,
+    types: Record<string, any>,
+    value: Record<string, any>
+  ): Promise<string>;
+}
+
+/**
+ * MessageSigner - Cryptographic signing for ACTP messages with EIP-712
+ * Reference: Yellow Paper §11.4.2
+ *
+ * V4 Security Enhancement: Optional nonce replay protection via ReceivedNonceTracker
+ */
+export class MessageSigner {
+  private domain: EIP712Domain | null = null;
+
+  constructor(
+    private readonly signer: Signer,
+    private readonly nonceTracker?: IReceivedNonceTracker
+  ) {}
+
+  /**
+   * Initialize EIP-712 domain (must be called before signing)
+   * @param kernelAddress - Address of ACTP Kernel contract
+   * @param chainId - Optional chainId (defaults to signer's chainId or 84532 for Base Sepolia)
+   */
+  async initDomain(kernelAddress: string, chainId?: number): Promise<void> {
+    let resolvedChainId: number;
+
+    if (chainId !== undefined) {
+      resolvedChainId = chainId;
+    } else {
+      try {
+        // ethers v6: signer.provider might be null, check first
+        if (this.signer.provider) {
+          const network = await this.signer.provider.getNetwork();
+          resolvedChainId = Number(network.chainId);
+        } else {
+          // Fallback to Base Sepolia for testing without provider
+          resolvedChainId = 84532;
+        }
+      } catch (error) {
+        // Fallback to Base Sepolia for testing without provider
+        resolvedChainId = 84532;
+      }
+    }
+
+    this.domain = {
+      name: 'ACTP',
+      version: '1.0',
+      chainId: resolvedChainId,
+      verifyingContract: kernelAddress
+    };
+  }
+
+  /**
+   * Sign ACTP message using EIP-712 typed data
+   * Uses ECDSA (secp256k1) with domain separation per Yellow Paper §11.4.2
+   * 
+   * Generic ACTPMessage format (backward compatible).
+   * For strict typed AIP messages, use signQuoteRequest/signQuoteResponse/signDeliveryProof
+   */
+  async signMessage(message: ACTPMessage): Promise<string> {
+    if (!this.domain) {
+      throw new Error('Domain not initialized. Call initDomain() first.');
+    }
+
+    const { type, version, from, to, timestamp, nonce, signature, ...payload } = message;
+
+    // Generic ACTPMessage with payload encoding (backward compatible)
+    const abiCoder = AbiCoder.defaultAbiCoder();
+    const payloadBytes = abiCoder.encode(
+      ['string'],
+      [this.canonicalizePayload(payload)]
+    );
+
+    const typedMessage = {
+      type,
+      version,
+      from,
+      to,
+      timestamp,
+      nonce,
+      payload: payloadBytes
+    };
+
+    // Use generic ACTPMessage types
+    const messageTypes = getMessageTypes('default');
+
+    // Sign using EIP-712 (ethers v6 API)
+    const signer = this.signer as SignerWithTypedData;
+    const sig = await signer.signTypedData(this.domain, messageTypes, typedMessage);
+
+    return sig;
+  }
+
+  /**
+   * Sign typed QuoteRequest message
+   */
+  async signQuoteRequest(data: QuoteRequestData): Promise<string> {
+    if (!this.domain) {
+      throw new Error('Domain not initialized. Call initDomain() first.');
+    }
+
+    const messageTypes = getMessageTypes('quote.request');
+    const signer = this.signer as SignerWithTypedData;
+    return await signer.signTypedData(this.domain, messageTypes, data);
+  }
+
+  /**
+   * Sign typed QuoteResponse message
+   */
+  async signQuoteResponse(data: QuoteResponseData): Promise<string> {
+    if (!this.domain) {
+      throw new Error('Domain not initialized. Call initDomain() first.');
+    }
+
+    const messageTypes = getMessageTypes('quote.response');
+    const signer = this.signer as SignerWithTypedData;
+    return await signer.signTypedData(this.domain, messageTypes, data);
+  }
+
+  /**
+   * Sign typed DeliveryProof message
+   */
+  async signDeliveryProof(data: DeliveryProofData): Promise<string> {
+    if (!this.domain) {
+      throw new Error('Domain not initialized. Call initDomain() first.');
+    }
+
+    const messageTypes = getMessageTypes('delivery.proof');
+    const signer = this.signer as SignerWithTypedData;
+    return await signer.signTypedData(this.domain, messageTypes, data);
+  }
+
+  /**
+   * Convenience helper to sign a DeliveryProof generated by ProofGenerator
+   */
+  async signGeneratedDeliveryProof(proof: DeliveryProof): Promise<string> {
+    const typedData = deliveryProofDataFromProof(proof);
+    return await this.signDeliveryProof(typedData);
+  }
+
+  /**
+   * Verify message signature using EIP-712
+   * Uses generic ACTPMessage types (backward compatible)
+   *
+   * V4 Security: If nonceTracker is configured, validates nonce for replay protection
+   */
+  async verifySignature(message: ACTPMessage, signature: string): Promise<boolean> {
+    if (!this.domain) {
+      throw new Error('Domain not initialized. Call initDomain() first.');
+    }
+
+    const { type, version, from, to, timestamp, nonce, signature: _, ...payload } = message;
+
+    const abiCoder = AbiCoder.defaultAbiCoder();
+    const payloadBytes = abiCoder.encode(
+      ['string'],
+      [this.canonicalizePayload(payload)]
+    );
+
+    const typedMessage = {
+      type,
+      version,
+      from,
+      to,
+      timestamp,
+      nonce,
+      payload: payloadBytes
+    };
+
+    // Use generic ACTPMessage types (backward compatible)
+    const messageTypes = getMessageTypes('default');
+    const recoveredAddress = ethers.verifyTypedData(
+      this.domain,
+      messageTypes,
+      typedMessage,
+      signature
+    );
+
+    const expectedAddress = this.didToAddress(from);
+
+    // Verify signature matches sender
+    if (recoveredAddress.toLowerCase() !== expectedAddress.toLowerCase()) {
+      return false;
+    }
+
+    // V4 Security: Validate nonce for replay protection (if tracker configured)
+    if (this.nonceTracker) {
+      const nonceValidation = this.nonceTracker.validateAndRecord(from, type, nonce);
+      if (!nonceValidation.valid) {
+        // Nonce replay detected - return false
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Verify signature and throw if invalid
+   * V4 Security: Throws specific error for nonce replay detection
+   */
+  async verifySignatureOrThrow(message: ACTPMessage, signature: string): Promise<void> {
+    if (!this.domain) {
+      throw new Error('Domain not initialized');
+    }
+
+    const { type, version, from, to, timestamp, nonce, signature: _, ...payload } = message;
+
+    const abiCoder = AbiCoder.defaultAbiCoder();
+    const payloadBytes = abiCoder.encode(
+      ['string'],
+      [this.canonicalizePayload(payload)]
+    );
+
+    const typedMessage = { type, version, from, to, timestamp, nonce, payload: payloadBytes };
+
+    const messageTypes = getMessageTypes('default');
+    const recoveredAddress = ethers.verifyTypedData(
+      this.domain,
+      messageTypes,
+      typedMessage,
+      signature
+    );
+
+    const expectedAddress = this.didToAddress(from);
+
+    // Check signature validity first
+    if (recoveredAddress.toLowerCase() !== expectedAddress.toLowerCase()) {
+      throw new SignatureVerificationError(expectedAddress, recoveredAddress);
+    }
+
+    // V4 Security: Validate nonce for replay protection (if tracker configured)
+    if (this.nonceTracker) {
+      const nonceValidation = this.nonceTracker.validateAndRecord(from, type, nonce);
+      if (!nonceValidation.valid) {
+        // Throw specific error for nonce replay
+        throw new Error(
+          `Nonce replay attack detected: ${nonceValidation.reason}. ` +
+          `Received nonce: ${nonceValidation.receivedNonce}. ` +
+          (nonceValidation.expectedMinimum ? `Expected minimum: ${nonceValidation.expectedMinimum}` : '')
+        );
+      }
+    }
+  }
+
+  /**
+   * Canonicalize payload to deterministic string (recursively sorted keys)
+   * Prevents JSON serialization ambiguity across different JS runtimes
+   * Recursively handles nested objects and arrays
+   */
+  private canonicalizePayload(payload: Record<string, any>): string {
+    return JSON.stringify(this.recursiveSort(payload));
+  }
+
+  /**
+   * Recursively sort object keys for deterministic JSON encoding
+   */
+  private recursiveSort(obj: any): any {
+    if (obj === null || obj === undefined) {
+      return obj;
+    }
+
+    // Handle arrays: recursively sort each element
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.recursiveSort(item));
+    }
+
+    // Handle objects: sort keys and recursively sort values
+    if (typeof obj === 'object' && obj.constructor === Object) {
+      const sortedKeys = Object.keys(obj).sort();
+      const canonical: Record<string, any> = {};
+
+      for (const key of sortedKeys) {
+        canonical[key] = this.recursiveSort(obj[key]);
+      }
+
+      return canonical;
+    }
+
+    // Primitives (string, number, boolean)
+    return obj;
+  }
+
+  /**
+   * Convert DID to Ethereum address
+   * MVP: Simple did:ethr → address conversion
+   */
+  private didToAddress(did: string): string {
+    if (did.startsWith('did:ethr:')) {
+      return did.replace('did:ethr:', '');
+    }
+
+    // If already an address, return as-is
+    if (ethers.isAddress(did)) {
+      return did;
+    }
+
+    throw new Error(`Invalid DID format: ${did}`);
+  }
+
+  /**
+   * Convert Ethereum address to DID
+   */
+  addressToDID(address: string): string {
+    if (!ethers.isAddress(address)) {
+      throw new Error(`Invalid Ethereum address: ${address}`);
+    }
+
+    return `did:ethr:${address}`;
+  }
+}

package/src/protocol/ProofGenerator.ts

@@ -0,0 +1,119 @@
+import { keccak256, toUtf8Bytes, AbiCoder, BytesLike } from 'ethers';
+import { DeliveryProof } from '../types';
+import { DeliveryProofData, deliveryProofDataFromProof } from '../types/eip712';
+
+/**
+ * ProofGenerator - Content hashing and delivery proofs
+ * Reference: Yellow Paper §11.4.1
+ */
+export class ProofGenerator {
+  /**
+   * Hash deliverable content
+   * Uses Keccak256 per Yellow Paper §11.4.1
+   */
+  hashContent(content: string | Buffer): string {
+    const buffer = typeof content === 'string' ? toUtf8Bytes(content) : content;
+
+    return keccak256(buffer);
+  }
+
+  /**
+   * Generate delivery proof (AIP-4)
+   * Reference: Yellow Paper §8.2
+   * Complete schema with type field for AIP compliance
+   * Computed fields (size, mimeType) cannot be overwritten
+   */
+  generateDeliveryProof(params: {
+    txId: string;
+    deliverable: string | Buffer;
+    deliveryUrl?: string;
+    metadata?: Record<string, any>;
+  }): DeliveryProof {
+    const { txId, deliverable, deliveryUrl, metadata = {} } = params;
+
+    const contentHash = this.hashContent(deliverable);
+    const size =
+      typeof deliverable === 'string'
+        ? Buffer.from(deliverable).length
+        : deliverable.length;
+
+    // Spread user metadata first, then enforce computed fields
+    // This prevents users from spoofing size/mimeType
+    const { size: _ignoredSize, mimeType: _ignoredMimeType, ...userMetadata } = metadata;
+
+    return {
+      type: 'delivery.proof', // Required per AIP-4
+      txId,
+      contentHash,
+      timestamp: Date.now(),
+      deliveryUrl, // Optional: IPFS/Arweave link
+      metadata: {
+        ...userMetadata, // User-supplied fields (excluding reserved)
+        size, // Enforced: computed from deliverable
+        mimeType: metadata.mimeType || 'application/octet-stream' // Enforced with fallback
+      }
+    };
+  }
+
+  /**
+   * Convert a generated delivery proof into typed EIP-712 data
+   */
+  toDeliveryProofTypedData(proof: DeliveryProof): DeliveryProofData {
+    return deliveryProofDataFromProof(proof);
+  }
+
+  /**
+   * Encode proof for on-chain submission
+   */
+  encodeProof(proof: DeliveryProof): BytesLike {
+    const abiCoder = AbiCoder.defaultAbiCoder();
+    return abiCoder.encode(
+      ['bytes32', 'bytes32', 'uint256'],
+      [proof.txId, proof.contentHash, proof.timestamp]
+    );
+  }
+
+  /**
+   * Decode proof from on-chain data
+   */
+  decodeProof(proofData: BytesLike): {
+    txId: string;
+    contentHash: string;
+    timestamp: number;
+  } {
+    const abiCoder = AbiCoder.defaultAbiCoder();
+    const [txId, contentHash, timestamp] = abiCoder.decode(
+      ['bytes32', 'bytes32', 'uint256'],
+      proofData
+    );
+
+    return {
+      txId,
+      contentHash,
+      timestamp: Number(timestamp)
+    };
+  }
+
+  /**
+   * Verify deliverable matches expected hash
+   */
+  verifyDeliverable(deliverable: string | Buffer, expectedHash: string): boolean {
+    const actualHash = this.hashContent(deliverable);
+    return actualHash.toLowerCase() === expectedHash.toLowerCase();
+  }
+
+  /**
+   * Generate content hash from URL (for IPFS/Arweave)
+   */
+  async hashFromUrl(url: string): Promise<string> {
+    // In browser/Node.js environment with fetch
+    try {
+      const response = await fetch(url);
+      const arrayBuffer = await response.arrayBuffer();
+      const buffer = Buffer.from(arrayBuffer);
+      return this.hashContent(buffer);
+    } catch (error) {
+      throw new Error(`Failed to fetch content from ${url}: ${error}`);
+    }
+  }
+}

package/src/protocol/QuoteBuilder.ts

@@ -0,0 +1,15 @@
+/**
+ * QuoteBuilder - AIP-2 Price Quote Construction
+ *
+ * This module re-exports the full QuoteBuilder implementation from builders/
+ * Reference: AIP-2 §6.1
+ *
+ * @deprecated Import from builders/QuoteBuilder directly
+ */
+
+export {
+  QuoteBuilder,
+  QuoteMessage,
+  QuoteParams,
+  AIP2QuoteTypes
+} from '../builders/QuoteBuilder';

package/src/types/eip712.ts

@@ -0,0 +1,175 @@
+import { DeliveryProof } from './message';
+
+/**
+ * EIP-712 Type Definitions for ACTP Messages
+ * Reference: Yellow Paper §11.4.2
+ * 
+ * Each AIP message has explicit typed data for cross-language compatibility
+ */
+
+/**
+ * EIP-712 Domain for ACTP
+ */
+export interface EIP712Domain {
+  name: string;
+  version: string;
+  chainId: number;
+  verifyingContract: string;
+}
+
+/**
+ * QuoteRequest (AIP-2)
+ * Reference: Yellow Paper §4.2
+ */
+export const QuoteRequestTypes = {
+  QuoteRequest: [
+    { name: 'from', type: 'string' }, // DID
+    { name: 'to', type: 'string' }, // DID
+    { name: 'timestamp', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+    { name: 'serviceType', type: 'string' },
+    { name: 'requirements', type: 'string' },
+    { name: 'deadline', type: 'uint256' },
+    { name: 'disputeWindow', type: 'uint256' }
+  ]
+};
+
+export interface QuoteRequestData {
+  from: string;
+  to: string;
+  timestamp: number;
+  nonce: string;
+  serviceType: string;
+  requirements: string;
+  deadline: number;
+  disputeWindow: number;
+}
+
+/**
+ * QuoteResponse (AIP-2)
+ * Reference: Yellow Paper §4.2
+ */
+export const QuoteResponseTypes = {
+  QuoteResponse: [
+    { name: 'from', type: 'string' },
+    { name: 'to', type: 'string' },
+    { name: 'timestamp', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+    { name: 'requestId', type: 'bytes32' },
+    { name: 'price', type: 'uint256' },
+    { name: 'currency', type: 'address' },
+    { name: 'deliveryTime', type: 'uint256' },
+    { name: 'terms', type: 'string' }
+  ]
+};
+
+export interface QuoteResponseData {
+  from: string;
+  to: string;
+  timestamp: number;
+  nonce: string;
+  requestId: string;
+  price: string; // BigNumber as string
+  currency: string;
+  deliveryTime: number;
+  terms: string;
+}
+
+/**
+ * DeliveryProof (AIP-4) - DEPRECATED
+ * @deprecated Use AIP4DeliveryProofTypes instead (AIP-4 v1.1)
+ */
+export const DeliveryProofTypes = {
+  DeliveryProof: [
+    { name: 'txId', type: 'bytes32' },
+    { name: 'contentHash', type: 'bytes32' },
+    { name: 'timestamp', type: 'uint256' },
+    { name: 'deliveryUrl', type: 'string' },
+    { name: 'size', type: 'uint256' },
+    { name: 'mimeType', type: 'string' }
+  ]
+};
+
+export interface DeliveryProofData {
+  txId: string;
+  contentHash: string;
+  timestamp: number;
+  deliveryUrl: string;
+  size: number;
+  mimeType: string;
+}
+
+export function deliveryProofDataFromProof(proof: DeliveryProof): DeliveryProofData {
+  return {
+    txId: proof.txId,
+    contentHash: proof.contentHash,
+    timestamp: proof.timestamp,
+    deliveryUrl: proof.deliveryUrl || '',
+    size: proof.metadata.size,
+    mimeType: proof.metadata.mimeType
+  };
+}
+
+/**
+ * AIP-4 Delivery Proof (v1.1)
+ * Reference: AIP-4 §3.3
+ */
+export const AIP4DeliveryProofTypes = {
+  DeliveryProof: [
+    { name: 'txId', type: 'bytes32' },
+    { name: 'provider', type: 'string' },
+    { name: 'consumer', type: 'string' },
+    { name: 'resultCID', type: 'string' },
+    { name: 'resultHash', type: 'bytes32' },
+    { name: 'easAttestationUID', type: 'bytes32' },
+    { name: 'deliveredAt', type: 'uint256' },
+    { name: 'chainId', type: 'uint256' },
+    { name: 'nonce', type: 'uint256' }
+  ]
+};
+
+export interface AIP4DeliveryProofData {
+  txId: string;
+  provider: string;
+  consumer: string;
+  resultCID: string;
+  resultHash: string;
+  easAttestationUID: string;
+  deliveredAt: number;
+  chainId: number;
+  nonce: number;
+}
+
+/**
+ * Generic ACTPMessage (fallback for custom AIPs)
+ */
+export const ACTPMessageTypes = {
+  ACTPMessage: [
+    { name: 'type', type: 'string' },
+    { name: 'version', type: 'string' },
+    { name: 'from', type: 'string' },
+    { name: 'to', type: 'string' },
+    { name: 'timestamp', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+    { name: 'payload', type: 'bytes' }
+  ]
+};
+
+/**
+ * Message type registry
+ */
+export const MESSAGE_TYPES = {
+  'quote.request': QuoteRequestTypes,
+  'quote.response': QuoteResponseTypes,
+  'delivery.proof': DeliveryProofTypes,
+  // Fallback for custom/future AIPs
+  default: ACTPMessageTypes
+};
+
+/**
+ * Get EIP-712 types for message type
+ */
+export function getMessageTypes(messageType: string): Record<string, any> {
+  return MESSAGE_TYPES[messageType as keyof typeof MESSAGE_TYPES] || MESSAGE_TYPES.default;
+}
+

package/src/types/escrow.ts

@@ -0,0 +1,26 @@
+/**
+ * Escrow creation parameters
+ */
+export interface CreateEscrowParams {
+  kernelAddress: string;
+  txId: string;
+  token: string;
+  amount: bigint;
+  beneficiary: string;
+}
+
+/**
+ * Escrow state
+ */
+export interface Escrow {
+  escrowId: string;
+  kernel: string;
+  txId: string;
+  token: string;
+  amount: bigint;
+  beneficiary: string;
+  createdAt: number;
+  released: boolean;
+}
+
+

package/src/types/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Type exports
+ */
+
+export * from './state';
+export * from './transaction';
+export * from './escrow';
+export * from './message';
+export * from './eip712';
+