clodds 1.1.0

package/dist/acp/escrow.js

@@ -0,0 +1,880 @@
+"use strict";
+/**
+ * On-Chain Escrow for Agent Commerce Protocol
+ *
+ * Secure escrow system for agent-to-agent transactions:
+ * - Deposit funds into escrow
+ * - Release on successful completion
+ * - Refund on failure/timeout
+ * - Dispute resolution
+ *
+ * Keypairs are stored encrypted in the database (AES-256-GCM)
+ * and cached in memory for performance.
+ *
+ * Supports both Solana (native) and EVM (Base) chains
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCustomCondition = registerCustomCondition;
+exports.unregisterCustomCondition = unregisterCustomCondition;
+exports.listCustomConditions = listCustomConditions;
+exports.createSolanaEscrowService = createSolanaEscrowService;
+exports.getEscrowService = getEscrowService;
+exports.initEscrowService = initEscrowService;
+exports.formatEscrowAmount = formatEscrowAmount;
+exports.createEscrowId = createEscrowId;
+exports.createOracleCondition = createOracleCondition;
+exports.isValidOracleCondition = isValidOracleCondition;
+const web3_js_1 = require("@solana/web3.js");
+const crypto = __importStar(require("crypto"));
+const bs58_1 = __importDefault(require("bs58"));
+const logger_1 = require("../utils/logger");
+const persistence_1 = require("./persistence");
+let splTokenModule = null;
+async function getSplToken() {
+    if (!splTokenModule) {
+        // Dynamic import for ESM compatibility
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const spl = await Promise.resolve().then(() => __importStar(require('@solana/spl-token')));
+        splTokenModule = {
+            getOrCreateAssociatedTokenAccount: spl.getOrCreateAssociatedTokenAccount,
+            transfer: spl.transfer,
+            getAccount: spl.getAccount,
+        };
+    }
+    return splTokenModule;
+}
+// =============================================================================
+// KEYPAIR ENCRYPTION (AES-256-GCM)
+// =============================================================================
+const ESCROW_ENCRYPTION_KEY = process.env.CLODDS_ESCROW_KEY || process.env.CLODDS_CREDENTIAL_KEY;
+const ENCRYPTION_ALGORITHM = 'aes-256-gcm';
+/**
+ * Encrypt a Solana keypair for database storage
+ */
+function encryptKeypair(keypair) {
+    if (!ESCROW_ENCRYPTION_KEY) {
+        throw new Error('CLODDS_ESCROW_KEY or CLODDS_CREDENTIAL_KEY required for escrow keypair encryption');
+    }
+    const secretKeyBase58 = bs58_1.default.encode(keypair.secretKey);
+    const salt = crypto.randomBytes(16);
+    const key = crypto.scryptSync(ESCROW_ENCRYPTION_KEY, salt, 32);
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv(ENCRYPTION_ALGORITHM, key, iv);
+    let encrypted = cipher.update(secretKeyBase58, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    const authTag = cipher.getAuthTag();
+    return [
+        'escrow_v1',
+        salt.toString('hex'),
+        iv.toString('hex'),
+        authTag.toString('hex'),
+        encrypted,
+    ].join(':');
+}
+/**
+ * Decrypt a Solana keypair from database storage
+ */
+function decryptKeypair(encryptedData) {
+    if (!ESCROW_ENCRYPTION_KEY) {
+        throw new Error('CLODDS_ESCROW_KEY or CLODDS_CREDENTIAL_KEY required for escrow keypair decryption');
+    }
+    const parts = encryptedData.split(':');
+    if (parts[0] !== 'escrow_v1' || parts.length < 5) {
+        throw new Error('Invalid escrow keypair format');
+    }
+    const [, saltHex, ivHex, authTagHex, encrypted] = parts;
+    const salt = Buffer.from(saltHex, 'hex');
+    const iv = Buffer.from(ivHex, 'hex');
+    const authTag = Buffer.from(authTagHex, 'hex');
+    const key = crypto.scryptSync(ESCROW_ENCRYPTION_KEY, salt, 32);
+    const decipher = crypto.createDecipheriv(ENCRYPTION_ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+    let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    const secretKey = bs58_1.default.decode(decrypted);
+    return web3_js_1.Keypair.fromSecretKey(secretKey);
+}
+// In-memory cache for performance (DB is source of truth)
+const escrowKeypairCache = new Map();
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const ESCROW_SEED = 'acp_escrow_v1';
+const ESCROW_TIMEOUT_DEFAULT = 7 * 24 * 60 * 60 * 1000; // 7 days
+/**
+ * Parse oracle condition value
+ * Format: "pyth:BTC/USD:gt:50000" or "http:https://api.example.com/price:lt:100:data.price"
+ */
+function parseOracleCondition(value) {
+    const parts = value.split(':');
+    if (parts.length < 4)
+        return null;
+    const [type, feedId, operator, targetStr, jsonPath] = parts;
+    if (!['pyth', 'http', 'switchboard'].includes(type))
+        return null;
+    if (!['gt', 'lt', 'gte', 'lte', 'eq'].includes(operator))
+        return null;
+    const targetValue = parseFloat(targetStr);
+    if (isNaN(targetValue))
+        return null;
+    return {
+        type: type,
+        feedId,
+        operator: operator,
+        targetValue,
+        jsonPath,
+    };
+}
+/**
+ * Compare values based on operator
+ */
+function compareValues(actual, operator, target) {
+    switch (operator) {
+        case 'gt': return actual > target;
+        case 'lt': return actual < target;
+        case 'gte': return actual >= target;
+        case 'lte': return actual <= target;
+        case 'eq': return Math.abs(actual - target) < 0.000001;
+        default: return false;
+    }
+}
+/**
+ * Get value from nested JSON path (e.g., "data.price" -> obj.data.price)
+ */
+function getJsonPathValue(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return null;
+        if (typeof current !== 'object')
+            return null;
+        current = current[part];
+    }
+    if (typeof current === 'number')
+        return current;
+    if (typeof current === 'string') {
+        const parsed = parseFloat(current);
+        return isNaN(parsed) ? null : parsed;
+    }
+    return null;
+}
+/**
+ * Fetch price from Pyth Network (Solana)
+ * Uses Pyth's price feed accounts
+ */
+async function fetchPythPrice(connection, feedId) {
+    try {
+        // Pyth price feed accounts on Solana mainnet
+        // feedId format: either full public key or known pairs like "BTC/USD"
+        const knownFeeds = {
+            'BTC/USD': 'GVXRSBjFk6e6J3NbVPXohDJetcTjaeeuykUpbQF8UoMU',
+            'ETH/USD': 'JBu1AL4obBcCMqKBBxhpWCNUt136ijcuMZLFvTP7iWdB',
+            'SOL/USD': 'H6ARHf6YXhGYeQfUzQNGk6rDNnLBQKrenN712K4AQJEG',
+            'USDC/USD': 'Gnt27xtC473ZT2Mw5u8wZ68Z3gULkSTb5DuxJy7eJotD',
+            'MATIC/USD': '7KVswB9vkCgeM3SHP7aGDijvdRAHK8P5wi9JXViCrtYh',
+        };
+        const feedPubkey = knownFeeds[feedId] || feedId;
+        const accountPubkey = new web3_js_1.PublicKey(feedPubkey);
+        const accountInfo = await connection.getAccountInfo(accountPubkey);
+        if (!accountInfo?.data) {
+            logger_1.logger.warn({ feedId }, 'Pyth price feed account not found');
+            return null;
+        }
+        // Parse Pyth price account (simplified - real impl would use @pythnetwork/client)
+        // Price is stored at offset 208, exponent at 212
+        const data = accountInfo.data;
+        if (data.length < 220)
+            return null;
+        const priceRaw = data.readBigInt64LE(208);
+        const expo = data.readInt32LE(216);
+        const price = Number(priceRaw) * Math.pow(10, expo);
+        logger_1.logger.debug({ feedId, price }, 'Fetched Pyth price');
+        return price;
+    }
+    catch (error) {
+        logger_1.logger.error({ feedId, error }, 'Failed to fetch Pyth price');
+        return null;
+    }
+}
+/**
+ * Fetch price from HTTP oracle endpoint
+ */
+async function fetchHttpOraclePrice(url, jsonPath) {
+    try {
+        const response = await fetch(url, {
+            headers: { 'Accept': 'application/json' },
+            signal: AbortSignal.timeout(10000), // 10s timeout
+        });
+        if (!response.ok) {
+            logger_1.logger.warn({ url, status: response.status }, 'HTTP oracle request failed');
+            return null;
+        }
+        const data = await response.json();
+        if (jsonPath) {
+            const value = getJsonPathValue(data, jsonPath);
+            if (value !== null) {
+                logger_1.logger.debug({ url, jsonPath, value }, 'Fetched HTTP oracle price');
+                return value;
+            }
+            logger_1.logger.warn({ url, jsonPath }, 'JSON path not found in response');
+            return null;
+        }
+        // If no path, try common patterns with type narrowing
+        if (typeof data === 'number')
+            return data;
+        if (data !== null && typeof data === 'object') {
+            const obj = data;
+            if (typeof obj.price === 'number')
+                return obj.price;
+            if (typeof obj.result === 'number')
+                return obj.result;
+            if (typeof obj.value === 'number')
+                return obj.value;
+            if (obj.data !== null && typeof obj.data === 'object') {
+                const nested = obj.data;
+                if (typeof nested.price === 'number')
+                    return nested.price;
+            }
+        }
+        logger_1.logger.warn({ url }, 'Could not extract price from HTTP oracle response');
+        return null;
+    }
+    catch (error) {
+        logger_1.logger.error({ url, error }, 'Failed to fetch HTTP oracle price');
+        return null;
+    }
+}
+/**
+ * Check oracle condition against live data
+ */
+async function checkOracleCondition(connection, config) {
+    let actualValue = null;
+    switch (config.type) {
+        case 'pyth':
+            actualValue = await fetchPythPrice(connection, config.feedId);
+            break;
+        case 'http':
+            actualValue = await fetchHttpOraclePrice(config.feedId, config.jsonPath);
+            break;
+        case 'switchboard': {
+            // Switchboard V2 AggregatorAccountData (packed, 8-byte Anchor discriminator):
+            // latestConfirmedRound starts at offset 341, result (SwitchboardDecimal) at +25 = 366
+            // SwitchboardDecimal = mantissa: i128 (16 bytes LE) + scale: u32 (4 bytes LE)
+            const SB_RESULT_OFFSET = 366;
+            const SB_MIN_ACCOUNT_SIZE = SB_RESULT_OFFSET + 20; // mantissa(16) + scale(4)
+            try {
+                const feedPubkey = new web3_js_1.PublicKey(config.feedId);
+                const accountInfo = await connection.getAccountInfo(feedPubkey);
+                if (!accountInfo?.data || accountInfo.data.length < SB_MIN_ACCOUNT_SIZE) {
+                    logger_1.logger.warn({ feedId: config.feedId }, 'Switchboard feed account not found or too small');
+                    return false;
+                }
+                const data = accountInfo.data;
+                const lo = data.readBigUInt64LE(SB_RESULT_OFFSET);
+                const hi = data.readBigInt64LE(SB_RESULT_OFFSET + 8);
+                const mantissa = (hi << 64n) | lo;
+                const scale = data.readUInt32LE(SB_RESULT_OFFSET + 16);
+                actualValue = Number(mantissa) / Math.pow(10, scale);
+                logger_1.logger.debug({ feedId: config.feedId, value: actualValue, scale }, 'Fetched Switchboard price');
+            }
+            catch (error) {
+                logger_1.logger.error({ feedId: config.feedId, error }, 'Failed to fetch Switchboard price');
+                return false;
+            }
+            break;
+        }
+    }
+    if (actualValue === null) {
+        logger_1.logger.warn({ config }, 'Could not fetch oracle value, treating condition as not met');
+        return false;
+    }
+    const result = compareValues(actualValue, config.operator, config.targetValue);
+    logger_1.logger.debug({ config, actualValue, result }, 'Oracle condition check result');
+    return result;
+}
+/**
+ * Registry for custom condition handlers
+ * Key is the condition name (from condition.value)
+ */
+const customConditionHandlers = new Map();
+/**
+ * Register a custom condition handler
+ * @param name - Unique name for the condition (e.g., "delivery_confirmed")
+ * @param handler - Async function that checks if condition is met
+ */
+function registerCustomCondition(name, handler) {
+    if (customConditionHandlers.has(name)) {
+        logger_1.logger.warn({ name }, 'Overwriting existing custom condition handler');
+    }
+    customConditionHandlers.set(name, handler);
+    logger_1.logger.info({ name }, 'Custom condition handler registered');
+}
+/**
+ * Unregister a custom condition handler
+ */
+function unregisterCustomCondition(name) {
+    return customConditionHandlers.delete(name);
+}
+/**
+ * List all registered custom condition handlers
+ */
+function listCustomConditions() {
+    return Array.from(customConditionHandlers.keys());
+}
+/**
+ * Check a custom condition using the registered handler
+ */
+async function checkCustomCondition(escrow, condition) {
+    const conditionName = typeof condition.value === 'string' ? condition.value : String(condition.value);
+    // Check if there's a registered handler
+    const handler = customConditionHandlers.get(conditionName);
+    if (!handler) {
+        logger_1.logger.warn({ conditionName, escrowId: escrow.id }, 'No handler registered for custom condition');
+        return false;
+    }
+    try {
+        const result = await handler(escrow, condition);
+        logger_1.logger.debug({ conditionName, escrowId: escrow.id, result }, 'Custom condition check result');
+        return result;
+    }
+    catch (error) {
+        logger_1.logger.error({ conditionName, escrowId: escrow.id, error }, 'Custom condition handler threw error');
+        return false;
+    }
+}
+// =============================================================================
+// BUILT-IN CUSTOM CONDITIONS
+// =============================================================================
+// Register some commonly useful built-in conditions
+registerCustomCondition('always_true', async () => true);
+registerCustomCondition('always_false', async () => false);
+// Time-window condition: "time_window:START_TS:END_TS"
+registerCustomCondition('time_window', async (_escrow, condition) => {
+    const [, startStr, endStr] = String(condition.value).split(':');
+    const start = parseInt(startStr, 10);
+    const end = parseInt(endStr, 10);
+    if (isNaN(start) || isNaN(end))
+        return false;
+    const now = Date.now();
+    return now >= start && now <= end;
+});
+// Escrow age condition: "min_age:MILLISECONDS" - escrow must be at least this old
+registerCustomCondition('min_age', async (escrow, condition) => {
+    const [, msStr] = String(condition.value).split(':');
+    const minAge = parseInt(msStr, 10);
+    if (isNaN(minAge))
+        return false;
+    return Date.now() - escrow.createdAt >= minAge;
+});
+// =============================================================================
+// KEYPAIR MANAGEMENT
+// =============================================================================
+/**
+ * Get escrow keypair - checks cache first, then loads from DB
+ */
+async function getEscrowKeypair(escrowId) {
+    // Check cache first
+    const cached = escrowKeypairCache.get(escrowId);
+    if (cached) {
+        return cached;
+    }
+    // Load from database
+    const persistence = (0, persistence_1.getEscrowPersistence)();
+    const encryptedKeypair = await persistence.getEncryptedKeypair(escrowId);
+    if (!encryptedKeypair) {
+        return null;
+    }
+    try {
+        const keypair = decryptKeypair(encryptedKeypair);
+        escrowKeypairCache.set(escrowId, keypair);
+        return keypair;
+    }
+    catch (error) {
+        logger_1.logger.error({ escrowId, error }, 'Failed to decrypt escrow keypair');
+        return null;
+    }
+}
+/**
+ * Store escrow keypair - saves to DB and caches in memory
+ */
+async function storeEscrowKeypair(escrowId, keypair) {
+    const encrypted = encryptKeypair(keypair);
+    const persistence = (0, persistence_1.getEscrowPersistence)();
+    await persistence.saveEncryptedKeypair(escrowId, encrypted);
+    escrowKeypairCache.set(escrowId, keypair);
+}
+/**
+ * Clear escrow keypair from cache and DB (after release/refund)
+ */
+async function clearEscrowKeypair(escrowId) {
+    escrowKeypairCache.delete(escrowId);
+    const persistence = (0, persistence_1.getEscrowPersistence)();
+    await persistence.clearEncryptedKeypair(escrowId);
+}
+// =============================================================================
+// SOLANA ESCROW IMPLEMENTATION
+// =============================================================================
+/**
+ * Derive escrow PDA address
+ */
+function deriveEscrowAddress(escrowId, programId) {
+    return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from(ESCROW_SEED), Buffer.from(escrowId)], programId);
+}
+/**
+ * Generate unique escrow ID
+ */
+function generateEscrowId() {
+    const timestamp = Date.now().toString(36);
+    const random = crypto.randomBytes(8).toString('hex');
+    return `escrow_${timestamp}_${random}`;
+}
+/**
+ * Hash escrow config for verification
+ */
+function hashEscrowConfig(config) {
+    const data = JSON.stringify({
+        buyer: config.buyer,
+        seller: config.seller,
+        amount: config.amount,
+        tokenMint: config.tokenMint,
+        expiresAt: config.expiresAt,
+    });
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+/**
+ * Create Solana escrow service with real on-chain transactions
+ */
+function createSolanaEscrowService(connection) {
+    const persistence = (0, persistence_1.getEscrowPersistence)();
+    return {
+        async create(config) {
+            const id = config.id || generateEscrowId();
+            // Generate escrow keypair for holding funds
+            const escrowKeypair = web3_js_1.Keypair.generate();
+            const escrow = {
+                ...config,
+                id,
+                status: 'pending',
+                createdAt: Date.now(),
+                escrowAddress: escrowKeypair.publicKey.toBase58(),
+                txSignatures: [],
+            };
+            // Save escrow record to database first (creates the row)
+            await persistence.save(escrow);
+            // Store keypair encrypted in database (UPDATE on existing row)
+            await storeEscrowKeypair(id, escrowKeypair);
+            logger_1.logger.info({ escrowId: id, buyer: config.buyer, seller: config.seller, amount: config.amount }, 'Escrow created with encrypted keypair');
+            return escrow;
+        },
+        async fund(escrowId, payer) {
+            const escrow = await persistence.get(escrowId);
+            if (!escrow) {
+                return { success: false, escrowId, error: 'Escrow not found' };
+            }
+            if (escrow.status !== 'pending') {
+                return { success: false, escrowId, error: `Cannot fund escrow in ${escrow.status} status` };
+            }
+            if (payer.publicKey.toBase58() !== escrow.buyer) {
+                return { success: false, escrowId, error: 'Only buyer can fund escrow' };
+            }
+            try {
+                const escrowPubkey = new web3_js_1.PublicKey(escrow.escrowAddress);
+                const amount = BigInt(escrow.amount);
+                if (escrow.tokenMint) {
+                    // SPL Token transfer using high-level helpers
+                    const spl = await getSplToken();
+                    const mintPubkey = new web3_js_1.PublicKey(escrow.tokenMint);
+                    // Get or create escrow's associated token account
+                    const escrowAta = await spl.getOrCreateAssociatedTokenAccount(connection, payer, mintPubkey, escrowPubkey, true // allowOwnerOffCurve - escrow keypair may not be on curve
+                    );
+                    // Get payer's token account
+                    const payerAta = await spl.getOrCreateAssociatedTokenAccount(connection, payer, mintPubkey, payer.publicKey);
+                    // Transfer SPL tokens to escrow
+                    const signature = await spl.transfer(connection, payer, payerAta.address, escrowAta.address, payer, amount);
+                    // Update escrow status
+                    escrow.status = 'funded';
+                    escrow.fundedAt = Date.now();
+                    escrow.txSignatures.push(signature);
+                    await persistence.save(escrow);
+                    logger_1.logger.info({ escrowId, signature, token: escrow.tokenMint }, 'SPL token escrow funded');
+                    return { success: true, escrowId, signature };
+                }
+                // Native SOL transfer to escrow account
+                const tx = new web3_js_1.Transaction().add(web3_js_1.SystemProgram.transfer({
+                    fromPubkey: payer.publicKey,
+                    toPubkey: escrowPubkey,
+                    lamports: amount,
+                }));
+                const signature = await (0, web3_js_1.sendAndConfirmTransaction)(connection, tx, [payer]);
+                // Update escrow status in database
+                escrow.status = 'funded';
+                escrow.fundedAt = Date.now();
+                escrow.txSignatures.push(signature);
+                await persistence.save(escrow);
+                logger_1.logger.info({ escrowId, signature }, 'Escrow funded');
+                return { success: true, escrowId, signature };
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                logger_1.logger.error({ escrowId, error: msg }, 'Failed to fund escrow');
+                return { success: false, escrowId, error: msg };
+            }
+        },
+        async release(escrowId, authorizer) {
+            const escrow = await persistence.get(escrowId);
+            if (!escrow) {
+                return { success: false, escrowId, error: 'Escrow not found' };
+            }
+            if (escrow.status !== 'funded') {
+                return { success: false, escrowId, error: `Cannot release escrow in ${escrow.status} status` };
+            }
+            const authAddress = authorizer.publicKey.toBase58();
+            if (authAddress !== escrow.buyer && authAddress !== escrow.arbiter) {
+                return { success: false, escrowId, error: 'Only buyer or arbiter can release' };
+            }
+            // Check release conditions
+            const conditionsMet = await this.checkConditions(escrowId, 'release');
+            if (!conditionsMet && authAddress !== escrow.arbiter) {
+                return { success: false, escrowId, error: 'Release conditions not met' };
+            }
+            try {
+                // Get escrow keypair from encrypted DB storage
+                const escrowKeypair = await getEscrowKeypair(escrowId);
+                if (!escrowKeypair) {
+                    return { success: false, escrowId, error: 'Escrow keypair not available - check CLODDS_ESCROW_KEY env var' };
+                }
+                const sellerPubkey = new web3_js_1.PublicKey(escrow.seller);
+                if (escrow.tokenMint) {
+                    // SPL Token release using high-level helpers
+                    const spl = await getSplToken();
+                    const mintPubkey = new web3_js_1.PublicKey(escrow.tokenMint);
+                    // Get escrow's token account
+                    const escrowAta = await spl.getOrCreateAssociatedTokenAccount(connection, escrowKeypair, mintPubkey, escrowKeypair.publicKey, true);
+                    // Get escrow token balance
+                    const tokenBalance = escrowAta.amount;
+                    if (tokenBalance <= BigInt(0)) {
+                        return { success: false, escrowId, error: 'Escrow token account is empty' };
+                    }
+                    // Get or create seller's token account
+                    const sellerAta = await spl.getOrCreateAssociatedTokenAccount(connection, escrowKeypair, // escrow pays for account creation
+                    mintPubkey, sellerPubkey);
+                    // Transfer tokens from escrow to seller
+                    const signature = await spl.transfer(connection, escrowKeypair, escrowAta.address, sellerAta.address, escrowKeypair, tokenBalance);
+                    // Update escrow
+                    escrow.status = 'released';
+                    escrow.completedAt = Date.now();
+                    escrow.txSignatures.push(signature);
+                    await persistence.save(escrow);
+                    await clearEscrowKeypair(escrowId);
+                    logger_1.logger.info({ escrowId, signature, seller: escrow.seller, token: escrow.tokenMint }, 'SPL token escrow released');
+                    return { success: true, escrowId, signature };
+                }
+                // Native SOL release
+                const amount = BigInt(escrow.amount);
+                // Get escrow account balance to handle any rent
+                const balance = await connection.getBalance(escrowKeypair.publicKey);
+                const transferAmount = BigInt(Math.min(Number(amount), balance));
+                if (transferAmount <= 0) {
+                    return { success: false, escrowId, error: 'Escrow account has no funds' };
+                }
+                // Transfer from escrow to seller
+                const tx = new web3_js_1.Transaction().add(web3_js_1.SystemProgram.transfer({
+                    fromPubkey: escrowKeypair.publicKey,
+                    toPubkey: sellerPubkey,
+                    lamports: transferAmount,
+                }));
+                const signature = await (0, web3_js_1.sendAndConfirmTransaction)(connection, tx, [escrowKeypair]);
+                // Update escrow in database
+                escrow.status = 'released';
+                escrow.completedAt = Date.now();
+                escrow.txSignatures.push(signature);
+                await persistence.save(escrow);
+                // Clear keypair from cache and DB (funds transferred, no longer needed)
+                await clearEscrowKeypair(escrowId);
+                logger_1.logger.info({ escrowId, signature, seller: escrow.seller }, 'Escrow released');
+                return { success: true, escrowId, signature };
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                logger_1.logger.error({ escrowId, error: msg }, 'Failed to release escrow');
+                return { success: false, escrowId, error: msg };
+            }
+        },
+        async refund(escrowId, authorizer) {
+            const escrow = await persistence.get(escrowId);
+            if (!escrow) {
+                return { success: false, escrowId, error: 'Escrow not found' };
+            }
+            if (escrow.status !== 'funded') {
+                return { success: false, escrowId, error: `Cannot refund escrow in ${escrow.status} status` };
+            }
+            const authAddress = authorizer.publicKey.toBase58();
+            const isExpired = Date.now() > escrow.expiresAt;
+            // Seller can refund anytime, buyer can refund if expired, arbiter can always refund
+            if (authAddress !== escrow.seller && authAddress !== escrow.arbiter) {
+                if (authAddress === escrow.buyer && !isExpired) {
+                    return { success: false, escrowId, error: 'Buyer can only refund after expiration' };
+                }
+                else if (authAddress !== escrow.buyer) {
+                    return { success: false, escrowId, error: 'Not authorized to refund' };
+                }
+            }
+            try {
+                // Get escrow keypair from encrypted DB storage
+                const escrowKeypair = await getEscrowKeypair(escrowId);
+                if (!escrowKeypair) {
+                    return { success: false, escrowId, error: 'Escrow keypair not available - check CLODDS_ESCROW_KEY env var' };
+                }
+                const buyerPubkey = new web3_js_1.PublicKey(escrow.buyer);
+                if (escrow.tokenMint) {
+                    // SPL Token refund using high-level helpers
+                    const spl = await getSplToken();
+                    const mintPubkey = new web3_js_1.PublicKey(escrow.tokenMint);
+                    // Get escrow's token account
+                    const escrowAta = await spl.getOrCreateAssociatedTokenAccount(connection, escrowKeypair, mintPubkey, escrowKeypair.publicKey, true);
+                    // Get escrow token balance
+                    const tokenBalance = escrowAta.amount;
+                    if (tokenBalance <= BigInt(0)) {
+                        return { success: false, escrowId, error: 'Escrow token account is empty' };
+                    }
+                    // Get or create buyer's token account (should exist since they funded)
+                    const buyerAta = await spl.getOrCreateAssociatedTokenAccount(connection, escrowKeypair, mintPubkey, buyerPubkey);
+                    // Transfer tokens back to buyer
+                    const signature = await spl.transfer(connection, escrowKeypair, escrowAta.address, buyerAta.address, escrowKeypair, tokenBalance);
+                    // Update escrow
+                    escrow.status = 'refunded';
+                    escrow.completedAt = Date.now();
+                    escrow.txSignatures.push(signature);
+                    await persistence.save(escrow);
+                    await clearEscrowKeypair(escrowId);
+                    logger_1.logger.info({ escrowId, signature, buyer: escrow.buyer, token: escrow.tokenMint }, 'SPL token escrow refunded');
+                    return { success: true, escrowId, signature };
+                }
+                // Native SOL refund
+                const balance = await connection.getBalance(escrowKeypair.publicKey);
+                if (balance <= 0) {
+                    return { success: false, escrowId, error: 'Escrow account has no funds' };
+                }
+                // Transfer from escrow back to buyer
+                const tx = new web3_js_1.Transaction().add(web3_js_1.SystemProgram.transfer({
+                    fromPubkey: escrowKeypair.publicKey,
+                    toPubkey: buyerPubkey,
+                    lamports: BigInt(balance),
+                }));
+                const signature = await (0, web3_js_1.sendAndConfirmTransaction)(connection, tx, [escrowKeypair]);
+                // Update escrow in database
+                escrow.status = 'refunded';
+                escrow.completedAt = Date.now();
+                escrow.txSignatures.push(signature);
+                await persistence.save(escrow);
+                // Clear keypair from cache and DB (funds transferred, no longer needed)
+                await clearEscrowKeypair(escrowId);
+                logger_1.logger.info({ escrowId, signature, buyer: escrow.buyer }, 'Escrow refunded');
+                return { success: true, escrowId, signature };
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                logger_1.logger.error({ escrowId, error: msg }, 'Failed to refund escrow');
+                return { success: false, escrowId, error: msg };
+            }
+        },
+        async dispute(escrowId, initiator, reason) {
+            const escrow = await persistence.get(escrowId);
+            if (!escrow) {
+                return { success: false, escrowId, error: 'Escrow not found' };
+            }
+            if (escrow.status !== 'funded') {
+                return { success: false, escrowId, error: 'Can only dispute funded escrows' };
+            }
+            if (!escrow.arbiter) {
+                return { success: false, escrowId, error: 'No arbiter configured for this escrow' };
+            }
+            const address = initiator.publicKey.toBase58();
+            if (address !== escrow.buyer && address !== escrow.seller) {
+                return { success: false, escrowId, error: 'Only buyer or seller can initiate dispute' };
+            }
+            escrow.status = 'disputed';
+            await persistence.save(escrow);
+            logger_1.logger.warn({ escrowId, initiator: address, reason }, 'Escrow disputed');
+            return { success: true, escrowId };
+        },
+        async resolveDispute(escrowId, arbiter, releaseTo) {
+            const escrow = await persistence.get(escrowId);
+            if (!escrow) {
+                return { success: false, escrowId, error: 'Escrow not found' };
+            }
+            if (escrow.status !== 'disputed') {
+                return { success: false, escrowId, error: 'Escrow is not in dispute' };
+            }
+            if (arbiter.publicKey.toBase58() !== escrow.arbiter) {
+                return { success: false, escrowId, error: 'Only arbiter can resolve disputes' };
+            }
+            // Temporarily set status back to funded so release/refund can proceed
+            escrow.status = 'funded';
+            await persistence.save(escrow);
+            if (releaseTo === 'seller') {
+                return this.release(escrowId, arbiter);
+            }
+            else {
+                return this.refund(escrowId, arbiter);
+            }
+        },
+        async get(escrowId) {
+            return persistence.get(escrowId);
+        },
+        async list(address, role) {
+            const all = await persistence.listByParty(address);
+            if (!role)
+                return all;
+            return all.filter(escrow => {
+                if (role === 'buyer')
+                    return escrow.buyer === address;
+                if (role === 'seller')
+                    return escrow.seller === address;
+                if (role === 'arbiter')
+                    return escrow.arbiter === address;
+                return false;
+            });
+        },
+        async checkConditions(escrowId, type) {
+            const escrow = await persistence.get(escrowId);
+            if (!escrow)
+                return false;
+            const conditions = type === 'release' ? escrow.releaseConditions : escrow.refundConditions;
+            for (const condition of conditions) {
+                switch (condition.type) {
+                    case 'time':
+                        // Time-based condition: check if current time is past the specified value
+                        if (Date.now() < Number(condition.value)) {
+                            logger_1.logger.debug({ escrowId, condition, now: Date.now() }, 'Time condition not met');
+                            return false;
+                        }
+                        break;
+                    case 'signature':
+                        // Signature condition: check if tx with required signature exists
+                        // Value should be the signature to look for
+                        if (typeof condition.value === 'string') {
+                            const hasSignature = escrow.txSignatures.some(sig => sig === condition.value);
+                            if (!hasSignature) {
+                                logger_1.logger.debug({ escrowId, condition }, 'Signature condition not met');
+                                return false;
+                            }
+                        }
+                        break;
+                    case 'oracle': {
+                        // Oracle condition: query external data source
+                        // Format: "pyth:BTC/USD:gt:50000" or "http:https://api.example.com:lt:100:data.price"
+                        const oracleConfig = parseOracleCondition(String(condition.value));
+                        if (!oracleConfig) {
+                            logger_1.logger.warn({ escrowId, condition }, 'Invalid oracle condition format');
+                            return false;
+                        }
+                        const oracleMet = await checkOracleCondition(connection, oracleConfig);
+                        if (!oracleMet) {
+                            logger_1.logger.debug({ escrowId, condition }, 'Oracle condition not met');
+                            return false;
+                        }
+                        break;
+                    }
+                    case 'custom': {
+                        // Custom condition: use registered handler
+                        const customMet = await checkCustomCondition(escrow, condition);
+                        if (!customMet) {
+                            logger_1.logger.debug({ escrowId, condition }, 'Custom condition not met');
+                            return false;
+                        }
+                        break;
+                    }
+                }
+            }
+            return true;
+        },
+    };
+}
+// =============================================================================
+// SINGLETON & EXPORTS
+// =============================================================================
+let escrowService = null;
+function getEscrowService(connection) {
+    if (!escrowService && connection) {
+        escrowService = createSolanaEscrowService(connection);
+    }
+    if (!escrowService) {
+        throw new Error('Escrow service not initialized. Provide a Connection.');
+    }
+    return escrowService;
+}
+function initEscrowService(connection) {
+    escrowService = createSolanaEscrowService(connection);
+    return escrowService;
+}
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+function formatEscrowAmount(amount, tokenMint) {
+    const value = BigInt(amount);
+    if (!tokenMint) {
+        // Native SOL
+        return `${(Number(value) / web3_js_1.LAMPORTS_PER_SOL).toFixed(4)} SOL`;
+    }
+    // Assume 6 decimals for most SPL tokens
+    return `${(Number(value) / 1_000_000).toFixed(2)} tokens`;
+}
+function createEscrowId() {
+    return generateEscrowId();
+}
+/**
+ * Create an oracle condition string
+ * @example createOracleCondition('pyth', 'BTC/USD', 'gt', 50000)
+ * @example createOracleCondition('http', 'https://api.example.com/price', 'lt', 100, 'data.price')
+ */
+function createOracleCondition(type, feedId, operator, targetValue, jsonPath) {
+    const parts = [type, feedId, operator, targetValue.toString()];
+    if (jsonPath)
+        parts.push(jsonPath);
+    return parts.join(':');
+}
+/**
+ * Validate an oracle condition string format
+ */
+function isValidOracleCondition(value) {
+    return parseOracleCondition(value) !== null;
+}
+//# sourceMappingURL=escrow.js.map