agent-escrow 0.1.0

package/src/marketplace.cjs

@@ -0,0 +1,362 @@
+'use strict';
+
+const {
+  KINDS, TASK_STATUS, RESOLUTION_TYPES,
+  connectRelays, publishToRelays, signEvent, pubkeyFromSecret,
+  closeRelays
+} = require('./nostr.cjs');
+const { createTaskEvent, updateTaskEvent, parseTask, findTasks, getTask } = require('./task.cjs');
+const { createBidEvent, parseBid, findBids, findMyBids } = require('./bid.cjs');
+const { createDeliveryEvent, parseDelivery, verifyDelivery, findDeliveries } = require('./delivery.cjs');
+const { createResolutionEvent, parseResolution, findResolutions } = require('./resolution.cjs');
+const { getTrustScore, meetsTrustThreshold, publishWorkAttestation, publishDisputeAttestation } = require('./trust.cjs');
+const { paymentsAvailable, createWallet, payWorker, checkBalance, createManualPaymentResult } = require('./escrow.cjs');
+
+/**
+ * Create a marketplace instance
+ *
+ * @param {Object} opts
+ * @param {string[]} opts.relays - Relay URLs
+ * @param {string|Uint8Array} opts.secretKey - Nostr secret key (hex or bytes)
+ * @param {string} [opts.nwcUrl] - NWC URL for Lightning payments
+ * @param {string} [opts.lightningAddress] - Your Lightning address
+ * @param {number} [opts.defaultMinTrust] - Default minimum trust for tasks
+ * @param {number} [opts.connectTimeoutMs] - Relay connection timeout
+ */
+function createMarketplace(opts) {
+  const {
+    relays: relayUrls = ['wss://relay.damus.io', 'wss://nos.lol'],
+    secretKey,
+    nwcUrl,
+    lightningAddress,
+    defaultMinTrust = 0,
+    connectTimeoutMs = 5000
+  } = opts;
+
+  if (!secretKey) throw new Error('secretKey is required');
+
+  const pubkey = pubkeyFromSecret(secretKey);
+  let relays = null;
+  let wallet = null;
+
+  /**
+   * Ensure relay connections are active
+   */
+  async function ensureConnected() {
+    if (!relays || relays.length === 0) {
+      relays = await connectRelays(relayUrls, connectTimeoutMs);
+      if (relays.length === 0) {
+        throw new Error('Failed to connect to any relay');
+      }
+    }
+    return relays;
+  }
+
+  /**
+   * Get or create wallet
+   */
+  function ensureWallet() {
+    if (!wallet && nwcUrl) {
+      wallet = createWallet(nwcUrl);
+    }
+    return wallet;
+  }
+
+  /**
+   * Sign and publish an event
+   */
+  async function signAndPublish(template) {
+    const r = await ensureConnected();
+    const event = signEvent(template, secretKey);
+    await publishToRelays(r, event);
+    return event;
+  }
+
+  // ── Task operations ───────────────────────────────────
+
+  /**
+   * Post a new task
+   */
+  async function postTask(taskOpts) {
+    const template = createTaskEvent({
+      ...taskOpts,
+      lightningAddress: taskOpts.lightningAddress || lightningAddress,
+      minTrust: taskOpts.minTrust ?? defaultMinTrust
+    });
+    const event = await signAndPublish(template);
+    return parseTask(event);
+  }
+
+  /**
+   * Cancel a task (only works if status is "open")
+   */
+  async function cancelTask(taskId) {
+    const r = await ensureConnected();
+    const task = await getTask(r, pubkey, taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+    if (task.status !== TASK_STATUS.OPEN) {
+      throw new Error(`Cannot cancel task in status: ${task.status}`);
+    }
+    const template = updateTaskEvent(task.raw, { status: TASK_STATUS.CANCELLED });
+    const event = await signAndPublish(template);
+    return parseTask(event);
+  }
+
+  /**
+   * Find open tasks on the network
+   */
+  async function browseTasks(searchOpts = {}) {
+    const r = await ensureConnected();
+    return findTasks(r, {
+      status: searchOpts.status || TASK_STATUS.OPEN,
+      ...searchOpts,
+      timeoutMs: searchOpts.timeoutMs || 8000
+    });
+  }
+
+  /**
+   * Get a specific task
+   */
+  async function fetchTask(posterPubkey, taskId) {
+    const r = await ensureConnected();
+    return getTask(r, posterPubkey, taskId);
+  }
+
+  // ── Bid operations ────────────────────────────────────
+
+  /**
+   * Submit a bid on a task
+   */
+  async function submitBid(bidOpts) {
+    const {
+      taskEventId,
+      posterPubkey,
+      amount,
+      eta,
+      message
+    } = bidOpts;
+
+    const template = createBidEvent({
+      taskEventId,
+      posterPubkey,
+      amount,
+      lightningAddress: bidOpts.lightningAddress || lightningAddress,
+      eta,
+      message
+    });
+
+    const event = await signAndPublish(template);
+    return parseBid(event);
+  }
+
+  /**
+   * Get bids for a task
+   */
+  async function getBids(taskEventId) {
+    const r = await ensureConnected();
+    return findBids(r, taskEventId);
+  }
+
+  /**
+   * Accept a bid — claims the task for the bidder
+   */
+  async function acceptBid(taskId, bid) {
+    const r = await ensureConnected();
+    const task = await getTask(r, pubkey, taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+    if (task.status !== TASK_STATUS.OPEN) {
+      throw new Error(`Cannot accept bid — task status is: ${task.status}`);
+    }
+
+    // Check bidder trust if threshold is set
+    if (task.minTrust && task.minTrust > 0) {
+      const meets = await meetsTrustThreshold(bid.bidder, task.minTrust, { relays: relayUrls });
+      if (!meets) {
+        throw new Error(`Bidder does not meet trust threshold (${task.minTrust})`);
+      }
+    }
+
+    const template = updateTaskEvent(task.raw, {
+      status: TASK_STATUS.CLAIMED,
+      workerPubkey: bid.bidder
+    });
+    const event = await signAndPublish(template);
+    return parseTask(event);
+  }
+
+  // ── Delivery operations ───────────────────────────────
+
+  /**
+   * Submit work for a task
+   */
+  async function deliver(deliveryOpts) {
+    const { taskEventId, posterPubkey, result } = deliveryOpts;
+
+    const template = createDeliveryEvent({
+      taskEventId,
+      posterPubkey,
+      result,
+      includeHash: deliveryOpts.includeHash
+    });
+
+    const event = await signAndPublish(template);
+    return parseDelivery(event);
+  }
+
+  /**
+   * Get deliveries for a task
+   */
+  async function getDeliveries(taskEventId) {
+    const r = await ensureConnected();
+    return findDeliveries(r, taskEventId);
+  }
+
+  // ── Resolution operations ─────────────────────────────
+
+  /**
+   * Approve delivery and pay the worker
+   *
+   * If wallet is configured, pays automatically.
+   * If not, returns a manual payment object for the caller to handle.
+   */
+  async function approve(approveOpts) {
+    const {
+      taskId,
+      workerPubkey,
+      workerLightningAddress,
+      amount,
+      message
+    } = approveOpts;
+
+    let payment = null;
+
+    // Try automatic payment
+    const w = ensureWallet();
+    if (w && workerLightningAddress) {
+      try {
+        payment = await payWorker(w, workerLightningAddress, amount, `agent-escrow: ${taskId}`);
+      } catch (e) {
+        // Payment failed — continue without payment proof
+        payment = { error: e.message, amountSats: amount };
+      }
+    } else {
+      payment = createManualPaymentResult(null, null, amount);
+    }
+
+    // Get the task event ID for the resolution
+    const r = await ensureConnected();
+    const task = await getTask(r, pubkey, taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+
+    // Publish resolution
+    const resTemplate = createResolutionEvent({
+      taskEventId: task.eventId,
+      workerPubkey,
+      type: RESOLUTION_TYPES.APPROVE,
+      paymentBolt11: payment.bolt11,
+      preimage: payment.preimage,
+      message
+    });
+    const resEvent = await signAndPublish(resTemplate);
+
+    // Update task status to completed
+    const taskTemplate = updateTaskEvent(task.raw, { status: TASK_STATUS.COMPLETED });
+    await signAndPublish(taskTemplate);
+
+    // Publish ai.wot attestation (non-blocking)
+    publishWorkAttestation({
+      targetPubkey: workerPubkey,
+      comment: `Completed task "${task.title}" — ${amount} sats via agent-escrow`,
+      secretKey,
+      relayUrls
+    }).catch(() => {}); // Non-fatal
+
+    return {
+      resolution: parseResolution(resEvent),
+      payment,
+      task: { ...task, status: TASK_STATUS.COMPLETED }
+    };
+  }
+
+  /**
+   * Dispute a delivery
+   */
+  async function dispute(disputeOpts) {
+    const { taskId, workerPubkey, reason } = disputeOpts;
+
+    const r = await ensureConnected();
+    const task = await getTask(r, pubkey, taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+
+    // Publish resolution
+    const resTemplate = createResolutionEvent({
+      taskEventId: task.eventId,
+      workerPubkey,
+      type: RESOLUTION_TYPES.DISPUTE,
+      message: reason
+    });
+    const resEvent = await signAndPublish(resTemplate);
+
+    // Update task status to disputed
+    const taskTemplate = updateTaskEvent(task.raw, { status: TASK_STATUS.DISPUTED });
+    await signAndPublish(taskTemplate);
+
+    // Publish negative attestation (non-blocking)
+    publishDisputeAttestation({
+      targetPubkey: workerPubkey,
+      comment: `Disputed task "${task.title}": ${reason}`,
+      secretKey,
+      relayUrls
+    }).catch(() => {}); // Non-fatal
+
+    return {
+      resolution: parseResolution(resEvent),
+      task: { ...task, status: TASK_STATUS.DISPUTED }
+    };
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────
+
+  /**
+   * Close all connections and clean up
+   */
+  async function close() {
+    if (relays) {
+      closeRelays(relays);
+      relays = null;
+    }
+    if (wallet && wallet.close) {
+      await wallet.close();
+      wallet = null;
+    }
+  }
+
+  return {
+    // Identity
+    pubkey,
+
+    // Tasks
+    postTask,
+    cancelTask,
+    browseTasks,
+    fetchTask,
+
+    // Bids
+    submitBid,
+    getBids,
+    acceptBid,
+
+    // Delivery
+    deliver,
+    getDeliveries,
+
+    // Resolution
+    approve,
+    dispute,
+
+    // Utility
+    close
+  };
+}
+
+module.exports = { createMarketplace };

package/src/nostr.cjs

@@ -0,0 +1,150 @@
+'use strict';
+
+const { finalizeEvent, getPublicKey } = require('nostr-tools/pure');
+const { Relay, useWebSocketImplementation } = require('nostr-tools/relay');
+
+// Use ws in Node.js
+try {
+  const WebSocket = require('ws');
+  useWebSocketImplementation(WebSocket);
+} catch (e) {
+  // Browser environment — native WebSocket available
+}
+
+// Event kinds
+const KINDS = {
+  TASK: 30950,       // Parameterized replaceable
+  BID: 950,          // Regular
+  DELIVERY: 951,     // Regular
+  RESOLUTION: 952    // Regular
+};
+
+const TASK_STATUS = {
+  OPEN: 'open',
+  CLAIMED: 'claimed',
+  DELIVERED: 'delivered',
+  COMPLETED: 'completed',
+  CANCELLED: 'cancelled',
+  DISPUTED: 'disputed',
+  EXPIRED: 'expired'
+};
+
+const RESOLUTION_TYPES = {
+  APPROVE: 'approve',
+  REJECT: 'reject',
+  DISPUTE: 'dispute'
+};
+
+/**
+ * Connect to multiple relays, return first successful connections
+ */
+async function connectRelays(urls, timeoutMs = 5000) {
+  const connected = [];
+  const results = await Promise.allSettled(
+    urls.map(url =>
+      Promise.race([
+        Relay.connect(url).then(r => { connected.push(r); return r; }),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), timeoutMs))
+      ])
+    )
+  );
+  return connected;
+}
+
+/**
+ * Publish event to multiple relays
+ */
+async function publishToRelays(relays, event) {
+  const results = await Promise.allSettled(
+    relays.map(r => r.publish(event))
+  );
+  const successes = results.filter(r => r.status === 'fulfilled').length;
+  if (successes === 0) {
+    throw new Error('Failed to publish to any relay');
+  }
+  return successes;
+}
+
+/**
+ * Query relays and collect events
+ */
+async function queryRelays(relays, filters, timeoutMs = 8000) {
+  const events = new Map(); // dedupe by id
+
+  await Promise.allSettled(
+    relays.map(relay =>
+      new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(), timeoutMs);
+        relay.subscribe(Array.isArray(filters) ? filters : [filters], {
+          onevent(event) {
+            events.set(event.id, event);
+          },
+          oneose() {
+            clearTimeout(timer);
+            resolve();
+          }
+        });
+      })
+    )
+  );
+
+  return Array.from(events.values());
+}
+
+/**
+ * Sign and finalize a Nostr event
+ */
+function signEvent(template, secretKey) {
+  const sk = typeof secretKey === 'string'
+    ? Uint8Array.from(Buffer.from(secretKey, 'hex'))
+    : secretKey;
+  return finalizeEvent(template, sk);
+}
+
+/**
+ * Get public key hex from secret key
+ */
+function pubkeyFromSecret(secretKey) {
+  const sk = typeof secretKey === 'string'
+    ? Uint8Array.from(Buffer.from(secretKey, 'hex'))
+    : secretKey;
+  return getPublicKey(sk);
+}
+
+/**
+ * Extract tag value from event
+ */
+function getTag(event, tagName) {
+  const tag = event.tags.find(t => t[0] === tagName);
+  return tag ? tag[1] : null;
+}
+
+/**
+ * Extract all values of a repeatable tag
+ */
+function getTags(event, tagName) {
+  return event.tags.filter(t => t[0] === tagName).map(t => t[1]);
+}
+
+/**
+ * Close all relay connections
+ */
+function closeRelays(relays) {
+  for (const r of relays) {
+    try { r.close(); } catch (e) { /* ignore */ }
+  }
+}
+
+module.exports = {
+  KINDS,
+  TASK_STATUS,
+  RESOLUTION_TYPES,
+  connectRelays,
+  publishToRelays,
+  queryRelays,
+  signEvent,
+  pubkeyFromSecret,
+  getTag,
+  getTags,
+  closeRelays
+};

package/src/resolution.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+const { KINDS, RESOLUTION_TYPES, queryRelays, getTag } = require('./nostr.cjs');
+
+/**
+ * Create a resolution event template
+ */
+function createResolutionEvent(opts) {
+  const {
+    taskEventId,
+    workerPubkey,
+    type,
+    paymentBolt11,
+    preimage,
+    message
+  } = opts;
+
+  if (!taskEventId) throw new Error('taskEventId is required');
+  if (!workerPubkey) throw new Error('workerPubkey is required');
+  if (!type || !Object.values(RESOLUTION_TYPES).includes(type)) {
+    throw new Error(`type must be one of: ${Object.values(RESOLUTION_TYPES).join(', ')}`);
+  }
+
+  // Disputes/rejections must include a reason
+  if ((type === RESOLUTION_TYPES.DISPUTE || type === RESOLUTION_TYPES.REJECT) && !message) {
+    throw new Error('message is required for dispute/reject resolutions');
+  }
+
+  const tags = [
+    ['e', taskEventId],
+    ['p', workerPubkey],
+    ['type', type]
+  ];
+
+  if (paymentBolt11) tags.push(['payment', paymentBolt11]);
+  if (preimage) tags.push(['preimage', preimage]);
+
+  return {
+    kind: KINDS.RESOLUTION,
+    created_at: Math.floor(Date.now() / 1000),
+    tags,
+    content: message || ''
+  };
+}
+
+/**
+ * Parse a resolution event into a structured object
+ */
+function parseResolution(event) {
+  return {
+    eventId: event.id,
+    poster: event.pubkey,
+    taskEventId: getTag(event, 'e'),
+    workerPubkey: getTag(event, 'p'),
+    type: getTag(event, 'type'),
+    paymentBolt11: getTag(event, 'payment'),
+    preimage: getTag(event, 'preimage'),
+    message: event.content,
+    createdAt: event.created_at * 1000,
+    raw: event
+  };
+}
+
+/**
+ * Find resolutions for a specific task
+ */
+async function findResolutions(relays, taskEventId, timeoutMs = 8000) {
+  const filter = {
+    kinds: [KINDS.RESOLUTION],
+    '#e': [taskEventId]
+  };
+  const events = await queryRelays(relays, filter, timeoutMs);
+  return events.map(parseResolution);
+}
+
+module.exports = {
+  createResolutionEvent,
+  parseResolution,
+  findResolutions
+};