@agirails/sdk 2.0.0-beta

package/src/utils/canonicalJson.ts

@@ -0,0 +1,38 @@
+/**
+ * Canonical JSON Serialization for AIP-4
+ * Reference: AIP-4 §3.6
+ *
+ * CRITICAL: Uses fast-json-stable-stringify@^2.1.0 for deterministic hashing
+ * This ensures resultHash is identical across all implementations (JS, Python, Go, Rust)
+ */
+
+import stringify from 'fast-json-stable-stringify';
+import { keccak256, toUtf8Bytes } from 'ethers';
+
+/**
+ * Canonical JSON stringify (sorted keys, no whitespace)
+ * @param obj - Any JSON-serializable object
+ * @returns Canonical JSON string
+ */
+export function canonicalJsonStringify(obj: any): string {
+  return stringify(obj);
+}
+
+/**
+ * Compute keccak256 hash of canonical JSON
+ * @param obj - Any JSON-serializable object
+ * @returns Keccak256 hash (0x-prefixed hex string)
+ */
+export function computeCanonicalHash(obj: any): string {
+  const canonical = canonicalJsonStringify(obj);
+  return keccak256(toUtf8Bytes(canonical));
+}
+
+/**
+ * Compute result hash for delivery proof (AIP-4)
+ * @param resultData - Service result data
+ * @returns Keccak256 hash of canonical result JSON
+ */
+export function computeResultHash(resultData: any): string {
+  return computeCanonicalHash(resultData);
+}

package/src/utils/computeTypeHash.ts

@@ -0,0 +1,50 @@
+/**
+ * Compute EIP-712 Type Hash for AIP-4 Delivery Proof
+ * Reference: AIP-4 §3.3, EIP-712 specification
+ *
+ * Run with: npx tsx src/utils/computeTypeHash.ts
+ */
+
+import { TypedDataEncoder, keccak256, toUtf8Bytes } from 'ethers';
+import { AIP4DeliveryProofTypes } from '../types/eip712';
+
+/**
+ * Compute EIP-712 type hash for DeliveryProof
+ * @returns Type hash (bytes32)
+ */
+export function computeDeliveryProofTypeHash(): string {
+  const encoder = TypedDataEncoder.from(AIP4DeliveryProofTypes);
+  const typeString = encoder.encodeType('DeliveryProof');
+
+  // Type hash is keccak256 of the encoded type string
+  const typeHash = keccak256(toUtf8Bytes(typeString));
+
+  return typeHash;
+}
+
+/**
+ * Get encoded type string for DeliveryProof
+ * @returns Type string (for documentation)
+ */
+export function getDeliveryProofTypeString(): string {
+  return TypedDataEncoder.from(AIP4DeliveryProofTypes).encodeType('DeliveryProof');
+}
+
+// If run directly, compute and print type hash
+if (require.main === module) {
+  console.log('=== AIP-4 Delivery Proof EIP-712 Type Hash ===\n');
+
+  const typeString = getDeliveryProofTypeString();
+  console.log('Type String:');
+  console.log(typeString);
+  console.log();
+
+  const typeHash = computeDeliveryProofTypeHash();
+  console.log('Type Hash (bytes32):');
+  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');
+}

package/src/utils/validation.ts

@@ -0,0 +1,82 @@
+import { isAddress, getAddress } from 'ethers';
+import {
+  InvalidAddressError,
+  InvalidAmountError,
+  ValidationError
+} from '../errors';
+
+/**
+ * Input validation utilities
+ */
+
+/**
+ * Validate Ethereum address
+ */
+export function validateAddress(address: string, fieldName: string = 'address'): void {
+  if (!address || !isAddress(address)) {
+    throw new InvalidAddressError(address);
+  }
+
+  if (address === getAddress('0x0000000000000000000000000000000000000000')) {
+    throw new ValidationError(fieldName, 'Address cannot be zero address');
+  }
+}
+
+/**
+ * Validate amount (must be > 0)
+ */
+export function validateAmount(amount: bigint, _fieldName: string = 'amount'): void {
+  // Handle null/undefined before calling toString()
+  if (!amount) {
+    throw new InvalidAmountError(String(amount)); // Convert safely to string
+  }
+
+  if (amount <= 0n) {
+    throw new InvalidAmountError(amount.toString());
+  }
+}
+
+/**
+ * Validate deadline (must be future timestamp)
+ */
+export function validateDeadline(deadline: number, fieldName: string = 'deadline'): void {
+  const now = Math.floor(Date.now() / 1000);
+  
+  if (deadline <= now) {
+    throw new ValidationError(
+      fieldName,
+      `Deadline must be in the future (now: ${now}, deadline: ${deadline})`
+    );
+  }
+}
+
+/**
+ * Validate dispute window (max 30 days per spec)
+ */
+export function validateDisputeWindow(
+  disputeWindow: number,
+  fieldName: string = 'disputeWindow'
+): void {
+  const MAX_DISPUTE_WINDOW = 30 * 24 * 60 * 60; // 30 days in seconds
+  
+  if (disputeWindow < 0) {
+    throw new ValidationError(fieldName, 'Dispute window cannot be negative');
+  }
+  
+  if (disputeWindow > MAX_DISPUTE_WINDOW) {
+    throw new ValidationError(
+      fieldName,
+      `Dispute window exceeds maximum (${MAX_DISPUTE_WINDOW}s = 30 days)`
+    );
+  }
+}
+
+/**
+ * Validate transaction ID format
+ */
+export function validateTxId(txId: string, fieldName: string = 'txId'): void {
+  if (!txId || !txId.match(/^0x[a-fA-F0-9]{64}$/)) {
+    throw new ValidationError(fieldName, 'Invalid transaction ID format (expected bytes32)');
+  }
+}
+