agent-escrow 0.1.0

package/src/cli.cjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createMarketplace, TASK_STATUS } = require('./index.cjs');
+const fs = require('fs');
+const path = require('path');
+
+const COMMANDS = {
+  'post': 'Post a new task',
+  'browse': 'Browse open tasks',
+  'bid': 'Bid on a task',
+  'bids': 'View bids for a task',
+  'deliver': 'Submit work for a task',
+  'approve': 'Approve delivery and pay worker',
+  'dispute': 'Dispute a delivery',
+  'cancel': 'Cancel an open task',
+  'help': 'Show this help'
+};
+
+function usage() {
+  console.log('agent-escrow — Decentralized marketplace for AI agents\n');
+  console.log('Usage: agent-escrow <command> [options]\n');
+  console.log('Commands:');
+  for (const [cmd, desc] of Object.entries(COMMANDS)) {
+    console.log(`  ${cmd.padEnd(12)} ${desc}`);
+  }
+  console.log('\nEnvironment:');
+  console.log('  NOSTR_SECRET_KEY   Nostr secret key (hex)');
+  console.log('  NWC_URL            Nostr Wallet Connect URL');
+  console.log('  LIGHTNING_ADDRESS   Your Lightning address');
+  console.log('  ESCROW_RELAYS      Comma-separated relay URLs');
+  console.log('\nOr provide a JSON config via --config <path>');
+}
+
+function parseArgs(args) {
+  const result = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const val = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
+      result[key] = val;
+    } else {
+      result._.push(args[i]);
+    }
+  }
+  return result;
+}
+
+function loadConfig(args) {
+  // Try config file
+  if (args.config) {
+    const raw = fs.readFileSync(args.config, 'utf8');
+    return JSON.parse(raw);
+  }
+
+  // Try environment
+  const secretKey = args['secret-key'] || process.env.NOSTR_SECRET_KEY;
+  if (!secretKey) {
+    console.error('Error: No secret key. Set NOSTR_SECRET_KEY or use --secret-key');
+    process.exit(1);
+  }
+
+  return {
+    secretKey,
+    nwcUrl: args['nwc-url'] || process.env.NWC_URL,
+    lightningAddress: args['ln-address'] || process.env.LIGHTNING_ADDRESS,
+    relays: (args.relays || process.env.ESCROW_RELAYS || 'wss://relay.damus.io,wss://nos.lol').split(',')
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+
+  if (!command || command === 'help') {
+    usage();
+    return;
+  }
+
+  if (!COMMANDS[command]) {
+    console.error(`Unknown command: ${command}\nRun 'agent-escrow help' for usage`);
+    process.exit(1);
+  }
+
+  const config = loadConfig(args);
+  const market = createMarketplace(config);
+
+  try {
+    switch (command) {
+      case 'post': {
+        const title = args.title || args._[1];
+        const budget = parseInt(args.budget || args._[2], 10);
+        if (!title || !budget) {
+          console.error('Usage: agent-escrow post --title "..." --budget <sats> [--caps "a,b"] [--min-trust N] [--deadline <ms>]');
+          process.exit(1);
+        }
+        const task = await market.postTask({
+          title,
+          description: args.description || args.desc || '',
+          budget,
+          capabilities: args.caps ? args.caps.split(',') : [],
+          minTrust: args['min-trust'] ? parseInt(args['min-trust'], 10) : undefined,
+          deadline: args.deadline ? parseInt(args.deadline, 10) : undefined
+        });
+        console.log('✅ Task posted!');
+        console.log(`   ID: ${task.taskId}`);
+        console.log(`   Title: ${task.title}`);
+        console.log(`   Budget: ${task.budget} sats`);
+        console.log(`   Event: ${task.eventId}`);
+        break;
+      }
+
+      case 'browse': {
+        const tasks = await market.browseTasks({
+          capabilities: args.caps ? args.caps.split(',') : undefined,
+          minBudget: args['min-budget'] ? parseInt(args['min-budget'], 10) : undefined,
+          maxBudget: args['max-budget'] ? parseInt(args['max-budget'], 10) : undefined,
+          limit: args.limit ? parseInt(args.limit, 10) : 20
+        });
+        if (tasks.length === 0) {
+          console.log('No open tasks found.');
+          return;
+        }
+        console.log(`Found ${tasks.length} open tasks:\n`);
+        for (const task of tasks) {
+          const caps = task.capabilities.length > 0 ? ` [${task.capabilities.join(', ')}]` : '';
+          const trust = task.minTrust ? ` (trust≥${task.minTrust})` : '';
+          console.log(`  📋 ${task.title}${caps}${trust}`);
+          console.log(`     Budget: ${task.budget} sats | Poster: ${task.poster.slice(0, 12)}...`);
+          console.log(`     Event: ${task.eventId}`);
+          if (task.description) console.log(`     ${task.description.slice(0, 100)}${task.description.length > 100 ? '...' : ''}`);
+          console.log();
+        }
+        break;
+      }
+
+      case 'bid': {
+        const taskEventId = args.task || args._[1];
+        const posterPubkey = args.poster || args._[2];
+        const amount = parseInt(args.amount || args._[3], 10);
+        if (!taskEventId || !posterPubkey || !amount) {
+          console.error('Usage: agent-escrow bid --task <event-id> --poster <pubkey> --amount <sats> [--message "..."] [--eta <ms>]');
+          process.exit(1);
+        }
+        const bid = await market.submitBid({
+          taskEventId,
+          posterPubkey,
+          amount,
+          message: args.message || '',
+          eta: args.eta ? parseInt(args.eta, 10) : undefined
+        });
+        console.log('✅ Bid submitted!');
+        console.log(`   Amount: ${bid.amount} sats`);
+        console.log(`   Event: ${bid.eventId}`);
+        break;
+      }
+
+      case 'bids': {
+        const taskEventId = args.task || args._[1];
+        if (!taskEventId) {
+          console.error('Usage: agent-escrow bids --task <event-id>');
+          process.exit(1);
+        }
+        const bids = await market.getBids(taskEventId);
+        if (bids.length === 0) {
+          console.log('No bids found.');
+          return;
+        }
+        console.log(`Found ${bids.length} bids:\n`);
+        for (const bid of bids) {
+          console.log(`  💰 ${bid.amount} sats — ${bid.bidder.slice(0, 12)}...`);
+          console.log(`     LN: ${bid.lightningAddress}`);
+          if (bid.message) console.log(`     "${bid.message}"`);
+          console.log(`     Event: ${bid.eventId}`);
+          console.log();
+        }
+        break;
+      }
+
+      case 'deliver': {
+        const taskEventId = args.task || args._[1];
+        const posterPubkey = args.poster || args._[2];
+        const result = args.result || args._[3];
+        if (!taskEventId || !posterPubkey || !result) {
+          console.error('Usage: agent-escrow deliver --task <event-id> --poster <pubkey> --result "..."');
+          process.exit(1);
+        }
+        // If result is a file path, read it
+        let deliverable = result;
+        if (fs.existsSync(result)) {
+          deliverable = fs.readFileSync(result, 'utf8');
+        }
+        const delivery = await market.deliver({
+          taskEventId,
+          posterPubkey,
+          result: deliverable
+        });
+        console.log('✅ Work delivered!');
+        console.log(`   Hash: ${delivery.hash}`);
+        console.log(`   Event: ${delivery.eventId}`);
+        break;
+      }
+
+      case 'approve': {
+        const taskId = args.task || args._[1];
+        const workerPubkey = args.worker || args._[2];
+        const workerLn = args['worker-ln'] || args._[3];
+        const amount = parseInt(args.amount || args._[4], 10);
+        if (!taskId || !workerPubkey || !amount) {
+          console.error('Usage: agent-escrow approve --task <task-id> --worker <pubkey> --amount <sats> [--worker-ln <address>]');
+          process.exit(1);
+        }
+        const result = await market.approve({
+          taskId,
+          workerPubkey,
+          workerLightningAddress: workerLn,
+          amount,
+          message: args.message
+        });
+        console.log('✅ Task approved!');
+        if (result.payment && result.payment.preimage) {
+          console.log(`   Payment: ${amount} sats`);
+          console.log(`   Preimage: ${result.payment.preimage}`);
+        } else if (result.payment && result.payment.manual) {
+          console.log(`   ⚠️  Manual payment needed: ${amount} sats to worker`);
+        }
+        break;
+      }
+
+      case 'dispute': {
+        const taskId = args.task || args._[1];
+        const workerPubkey = args.worker || args._[2];
+        const reason = args.reason || args._[3];
+        if (!taskId || !workerPubkey || !reason) {
+          console.error('Usage: agent-escrow dispute --task <task-id> --worker <pubkey> --reason "..."');
+          process.exit(1);
+        }
+        await market.dispute({ taskId, workerPubkey, reason });
+        console.log('⚠️  Task disputed.');
+        console.log(`   Reason: ${reason}`);
+        break;
+      }
+
+      case 'cancel': {
+        const taskId = args.task || args._[1];
+        if (!taskId) {
+          console.error('Usage: agent-escrow cancel --task <task-id>');
+          process.exit(1);
+        }
+        await market.cancelTask(taskId);
+        console.log('✅ Task cancelled.');
+        break;
+      }
+    }
+  } finally {
+    await market.close();
+  }
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/src/delivery.cjs

@@ -0,0 +1,85 @@
+'use strict';
+
+const crypto = require('crypto');
+const { KINDS, queryRelays, getTag } = require('./nostr.cjs');
+
+/**
+ * Create a delivery event template
+ */
+function createDeliveryEvent(opts) {
+  const {
+    taskEventId,
+    posterPubkey,
+    result,
+    includeHash
+  } = opts;
+
+  if (!taskEventId) throw new Error('taskEventId is required');
+  if (!posterPubkey) throw new Error('posterPubkey is required');
+  if (!result) throw new Error('result is required');
+
+  const tags = [
+    ['e', taskEventId],
+    ['p', posterPubkey]
+  ];
+
+  if (includeHash !== false) {
+    const hash = crypto.createHash('sha256').update(result).digest('hex');
+    tags.push(['hash', hash]);
+  }
+
+  return {
+    kind: KINDS.DELIVERY,
+    created_at: Math.floor(Date.now() / 1000),
+    tags,
+    content: result
+  };
+}
+
+/**
+ * Parse a delivery event into a structured object
+ */
+function parseDelivery(event) {
+  return {
+    eventId: event.id,
+    worker: event.pubkey,
+    taskEventId: getTag(event, 'e'),
+    posterPubkey: getTag(event, 'p'),
+    result: event.content,
+    hash: getTag(event, 'hash'),
+    createdAt: event.created_at * 1000,
+    raw: event
+  };
+}
+
+/**
+ * Verify delivery hash matches content
+ */
+function verifyDelivery(delivery) {
+  if (!delivery.hash) return { valid: true, reason: 'no hash to verify' };
+  const computed = crypto.createHash('sha256').update(delivery.result).digest('hex');
+  return {
+    valid: computed === delivery.hash,
+    expected: delivery.hash,
+    actual: computed
+  };
+}
+
+/**
+ * Find deliveries for a specific task
+ */
+async function findDeliveries(relays, taskEventId, timeoutMs = 8000) {
+  const filter = {
+    kinds: [KINDS.DELIVERY],
+    '#e': [taskEventId]
+  };
+  const events = await queryRelays(relays, filter, timeoutMs);
+  return events.map(parseDelivery);
+}
+
+module.exports = {
+  createDeliveryEvent,
+  parseDelivery,
+  verifyDelivery,
+  findDeliveries
+};

package/src/escrow.cjs

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * Payment coordination — optional lightning-agent dependency
+ *
+ * Handles Lightning payments between poster and worker.
+ * Falls back gracefully if lightning-agent is not installed.
+ */
+
+let lightningAgent = null;
+try {
+  lightningAgent = require('lightning-agent');
+} catch (e) {
+  // lightning-agent not installed — payment features require manual handling
+}
+
+/**
+ * Check if Lightning payment features are available
+ */
+function paymentsAvailable() {
+  return lightningAgent !== null;
+}
+
+/**
+ * Create a wallet instance from NWC URL
+ */
+function createWallet(nwcUrl) {
+  if (!lightningAgent) {
+    throw new Error('lightning-agent is required for payment features. Install with: npm install lightning-agent');
+  }
+  return lightningAgent.createWallet(nwcUrl);
+}
+
+/**
+ * Pay a worker by resolving their Lightning address and paying
+ */
+async function payWorker(wallet, lightningAddress, amountSats, memo) {
+  if (!lightningAgent) {
+    throw new Error('lightning-agent is required for payment features');
+  }
+
+  // Resolve Lightning address to get invoice
+  const invoice = await lightningAgent.resolveLightningAddress
+    ? await resolveAndPay(wallet, lightningAddress, amountSats, memo)
+    : await wallet.payAddress(lightningAddress, amountSats * 1000, memo);
+
+  return invoice;
+}
+
+/**
+ * Internal: resolve address and pay
+ */
+async function resolveAndPay(wallet, address, amountSats, memo) {
+  const resolved = await lightningAgent.resolveLightningAddress(address, amountSats * 1000);
+  if (!resolved || !resolved.pr) {
+    throw new Error(`Failed to resolve Lightning address: ${address}`);
+  }
+  const result = await wallet.payInvoice(resolved.pr);
+  return {
+    bolt11: resolved.pr,
+    preimage: result.preimage,
+    amountSats
+  };
+}
+
+/**
+ * Check wallet balance
+ */
+async function checkBalance(wallet) {
+  if (!wallet || !wallet.getBalance) return null;
+  try {
+    const balance = await wallet.getBalance();
+    return balance;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Payment result object for manual payment flows
+ */
+function createManualPaymentResult(bolt11, preimage, amountSats) {
+  return {
+    bolt11: bolt11 || null,
+    preimage: preimage || null,
+    amountSats,
+    manual: true
+  };
+}
+
+module.exports = {
+  paymentsAvailable,
+  createWallet,
+  payWorker,
+  checkBalance,
+  createManualPaymentResult
+};

package/src/index.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+const { createMarketplace } = require('./marketplace.cjs');
+const { KINDS, TASK_STATUS, RESOLUTION_TYPES } = require('./nostr.cjs');
+const { createTaskEvent, parseTask, findTasks, getTask } = require('./task.cjs');
+const { createBidEvent, parseBid, findBids } = require('./bid.cjs');
+const { createDeliveryEvent, parseDelivery, verifyDelivery, findDeliveries } = require('./delivery.cjs');
+const { createResolutionEvent, parseResolution, findResolutions } = require('./resolution.cjs');
+const { trustAvailable, getTrustScore, meetsTrustThreshold } = require('./trust.cjs');
+const { paymentsAvailable } = require('./escrow.cjs');
+
+module.exports = {
+  // Main factory
+  createMarketplace,
+
+  // Constants
+  KINDS,
+  TASK_STATUS,
+  RESOLUTION_TYPES,
+
+  // Low-level event creators (for custom flows)
+  createTaskEvent,
+  createBidEvent,
+  createDeliveryEvent,
+  createResolutionEvent,
+
+  // Parsers
+  parseTask,
+  parseBid,
+  parseDelivery,
+  parseResolution,
+
+  // Queries
+  findTasks,
+  findBids,
+  findDeliveries,
+  findResolutions,
+  getTask,
+
+  // Verification
+  verifyDelivery,
+
+  // Trust
+  trustAvailable,
+  getTrustScore,
+  meetsTrustThreshold,
+
+  // Payments
+  paymentsAvailable
+};