@toon-protocol/sdk 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,3 +1,5 @@
+import "./chunk-UP2VWCW5.js";
+
 // src/identity.ts
 import {
   generateMnemonic as _generateMnemonic,
@@ -140,7 +142,6 @@ function toChecksumAddress(addressHex) {
 }
 
 // src/handler-context.ts
-import { createHash } from "crypto";
 function createHandlerContext(options) {
   let cachedEvent;
   return {
@@ -166,11 +167,8 @@ function createHandlerContext(options) {
       return cachedEvent;
     },
     accept(metadata) {
-      const toonBytes = Buffer.from(options.toon, "base64");
-      const fulfillment = createHash("sha256").update(toonBytes).digest().toString("base64");
       return {
         accept: true,
-        fulfillment,
         ...metadata ? { metadata } : {}
       };
     },
@@ -381,7 +379,15 @@ import {
   buildIlpPrepare,
   buildJobFeedbackEvent,
   buildJobResultEvent,
-  parseJobResult
+  parseJobResult,
+  deriveChildAddress,
+  checkAddressCollision,
+  AddressRegistry,
+  ILP_ROOT_PREFIX,
+  calculateRouteAmount,
+  resolveRouteFees,
+  buildPrefixClaimEvent,
+  validatePrefix
 } from "@toon-protocol/core";
 import {
   shallowParseToon,
@@ -390,11 +396,21 @@ import {
 } from "@toon-protocol/core/toon";
 
 // src/skill-descriptor.ts
+import { ToonError as ToonError2 } from "@toon-protocol/core";
+var HEX_64_REGEX = /^[0-9a-f]{64}$/;
 function buildSkillDescriptor(registry, config = {}) {
   const dvmKinds = registry.getDvmKinds();
   if (dvmKinds.length === 0) {
     return void 0;
   }
+  if (config.attestation !== void 0) {
+    if (!HEX_64_REGEX.test(config.attestation.eventId)) {
+      throw new ToonError2(
+        "Skill descriptor attestation eventId must be a 64-character lowercase hex string",
+        "DVM_SKILL_INVALID_ATTESTATION_EVENT_ID"
+      );
+    }
+  }
   const basePricePerByte = config.basePricePerByte ?? 10n;
   const kindPricing = config.kindPricing ?? {};
   const pricing = {};
@@ -416,6 +432,15 @@ function buildSkillDescriptor(registry, config = {}) {
   if (config.models !== void 0) {
     descriptor.models = config.models;
   }
+  if (config.reputation !== void 0) {
+    descriptor.reputation = config.reputation;
+  }
+  if (config.attestation !== void 0) {
+    descriptor.attestation = {
+      eventId: config.attestation.eventId,
+      enclaveImageHash: config.attestation.enclaveImageHash
+    };
+  }
   return descriptor;
 }
 
@@ -578,11 +603,54 @@ function createNode(config) {
       return { accept: false, code: "T00", message: "Internal error" };
     }
   };
+  let resolvedIlpAddress;
+  let resolvedIlpAddresses;
+  if (config.upstreamPrefixes !== void 0 && config.upstreamPrefixes.length > 0) {
+    if (config.upstreamPrefix !== void 0) {
+      console.warn(
+        "[toon:warn] Both upstreamPrefixes and upstreamPrefix set; upstreamPrefixes takes priority"
+      );
+    }
+    resolvedIlpAddresses = config.upstreamPrefixes.map(
+      (p) => deriveChildAddress(p, pubkey)
+    );
+    for (let i = 0; i < resolvedIlpAddresses.length; i++) {
+      const others = resolvedIlpAddresses.filter((_, j) => j !== i);
+      checkAddressCollision(resolvedIlpAddresses[i], others);
+    }
+    resolvedIlpAddress = resolvedIlpAddresses[0];
+  } else if (config.upstreamPrefix !== void 0) {
+    resolvedIlpAddress = deriveChildAddress(config.upstreamPrefix, pubkey);
+    resolvedIlpAddresses = [resolvedIlpAddress];
+  } else if (config.ilpAddress !== void 0) {
+    resolvedIlpAddress = config.ilpAddress;
+    resolvedIlpAddresses = [resolvedIlpAddress];
+  } else {
+    resolvedIlpAddress = deriveChildAddress(ILP_ROOT_PREFIX, pubkey);
+    resolvedIlpAddresses = [resolvedIlpAddress];
+  }
+  const addressRegistry = new AddressRegistry();
+  if (config.upstreamPrefixes !== void 0 && config.upstreamPrefixes.length > 0) {
+    for (let i = 0; i < config.upstreamPrefixes.length; i++) {
+      addressRegistry.addAddress(
+        config.upstreamPrefixes[i],
+        resolvedIlpAddresses[i]
+      );
+    }
+  } else if (config.upstreamPrefix !== void 0) {
+    addressRegistry.addAddress(config.upstreamPrefix, resolvedIlpAddress);
+  } else if (config.ilpAddress !== void 0) {
+    addressRegistry.addAddress("explicit", resolvedIlpAddress);
+  } else {
+    addressRegistry.addAddress(ILP_ROOT_PREFIX, resolvedIlpAddress);
+  }
   const ilpInfo = {
-    ilpAddress: config.ilpAddress ?? "g.toon.local",
+    ilpAddress: resolvedIlpAddress,
+    ilpAddresses: resolvedIlpAddresses,
     btpEndpoint: config.btpEndpoint ?? "",
     assetCode: config.assetCode ?? "USD",
-    assetScale: config.assetScale ?? 6
+    assetScale: config.assetScale ?? 6,
+    feePerByte: String(config.feePerByte ?? 0n)
   };
   let ilpClient;
   let adminClient;
@@ -667,6 +735,7 @@ function createNode(config) {
         keyBuffer.fill(0);
       }
       const hasSettlementAddresses = chainConfig.registryAddress && chainConfig.tokenNetworkAddress;
+      const hasChainProviders = config.chainProviders !== void 0 && config.chainProviders.length > 0;
       autoCreatedConnector = new ConnectorNodeClass(
         {
           nodeId,
@@ -676,7 +745,12 @@ function createNode(config) {
           peers: [],
           routes: [],
           localDelivery: { enabled: false },
-          ...hasSettlementAddresses && {
+          // Multi-chain: use chainProviders when provided
+          ...hasChainProviders && {
+            chainProviders: config.chainProviders
+          },
+          // Legacy: fall back to settlementInfra when chainProviders absent
+          ...!hasChainProviders && hasSettlementAddresses && {
             settlementInfra: {
               enabled: true,
               rpcUrl: chainConfig.rpcUrl,
@@ -684,7 +758,9 @@ function createNode(config) {
               tokenAddress: chainConfig.usdcAddress,
               privateKey: settlementPrivateKey
             }
-          }
+          },
+          // NIP-59 transport privacy
+          ...config.nip59 && { nip59: config.nip59 }
         },
         connectorLogger
       );
@@ -721,11 +797,13 @@ function createNode(config) {
         discoveryTrackerInstance.setChannelClient(toonNode.channelClient);
       }
       trackerRef.current = discoveryTrackerInstance;
-      autoCreatedConnector.addRoute({
-        prefix: ilpInfo.ilpAddress,
-        nextHop: nodeId,
-        priority: 100
-      });
+      for (const addr of ilpInfo.ilpAddresses) {
+        autoCreatedConnector.addRoute({
+          prefix: addr,
+          nextHop: nodeId,
+          priority: 100
+        });
+      }
       const result = await toonNode.start();
       return result;
     };
@@ -842,6 +920,7 @@ function createNode(config) {
     };
   }
   let started = false;
+  let lastBootstrapResults = [];
   const node = {
     get pubkey() {
       return pubkey;
@@ -893,6 +972,7 @@ function createNode(config) {
       try {
         const result = await doStart();
         started = true;
+        lastBootstrapResults = result.bootstrapResults;
         return {
           peerCount: result.peerCount,
           channelCount: result.channelCount,
@@ -941,7 +1021,35 @@ function createNode(config) {
       }
       try {
         const toonData = encoder(event);
-        const amount = (config.basePricePerByte ?? 10n) * BigInt(toonData.length);
+        const { hopFees, warnings } = resolveRouteFees({
+          destination: options.destination,
+          ownIlpAddress: ilpInfo.ilpAddress,
+          discoveredPeers: discoveryTrackerInstance.getAllDiscoveredPeers()
+        });
+        for (const warning of warnings) {
+          console.warn(`[publishEvent] ${warning}`);
+        }
+        const destinationAmount = options.amount ?? (config.basePricePerByte ?? 10n) * BigInt(toonData.length);
+        if (options.bid !== void 0 && destinationAmount > options.bid) {
+          throw new NodeError(
+            `Cannot publish: destination amount ${destinationAmount} exceeds bid safety cap ${options.bid}`
+          );
+        }
+        let amount;
+        if (options.amount !== void 0) {
+          const hopFeesTotal = calculateRouteAmount({
+            basePricePerByte: 0n,
+            packetByteLength: toonData.length,
+            hopFees
+          });
+          amount = options.amount + hopFeesTotal;
+        } else {
+          amount = calculateRouteAmount({
+            basePricePerByte: config.basePricePerByte ?? 10n,
+            packetByteLength: toonData.length,
+            hopFees
+          });
+        }
         const packet = buildIlpPrepare({
           destination: options.destination,
           amount,
@@ -952,7 +1060,7 @@ function createNode(config) {
           return {
             success: true,
             eventId: event.id,
-            fulfillment: result.fulfillment ?? ""
+            ...result.data !== void 0 ? { data: result.data } : {}
           };
         }
         return {
@@ -987,6 +1095,9 @@ function createNode(config) {
       return node.publishEvent(resultEvent, options);
     },
     async settleCompute(resultEvent, providerIlpAddress, options) {
+      console.warn(
+        "[settleCompute] DEPRECATED: Use publishEvent() with { amount } option instead. The prepaid model sends job request + payment in one packet."
+      );
       if (!started) {
         throw new NodeError(
           "Cannot settle compute: node not started. Call start() first."
@@ -1037,26 +1148,944 @@ function createNode(config) {
         amount: computeAmount,
         data: ""
       });
+    },
+    // Task 6.3: Address lifecycle management for multi-peered nodes
+    addUpstreamPeer(upstreamPrefix) {
+      const derivedAddress = deriveChildAddress(upstreamPrefix, pubkey);
+      checkAddressCollision(derivedAddress, addressRegistry.getAddresses());
+      addressRegistry.addAddress(upstreamPrefix, derivedAddress);
+      ilpInfo.ilpAddresses = addressRegistry.getAddresses();
+      ilpInfo.ilpAddress = addressRegistry.getPrimaryAddress() ?? ilpInfo.ilpAddress;
+      if (autoCreatedConnector) {
+        const nodeId = `toon-${pubkey.slice(0, 16)}`;
+        autoCreatedConnector.addRoute({
+          prefix: derivedAddress,
+          nextHop: nodeId,
+          priority: 100
+        });
+      }
+      if (started && lastBootstrapResults.length > 0) {
+        void bootstrapServiceInstance.republish(lastBootstrapResults);
+      }
+    },
+    removeUpstreamPeer(upstreamPrefix) {
+      if (addressRegistry.hasPrefix(upstreamPrefix) && addressRegistry.size <= 1) {
+        throw new NodeError(
+          "Cannot remove last upstream peer: a node must have at least one ILP address"
+        );
+      }
+      const removedAddress = addressRegistry.removeAddress(upstreamPrefix);
+      if (removedAddress === void 0) {
+        return;
+      }
+      ilpInfo.ilpAddresses = addressRegistry.getAddresses();
+      const newPrimary = addressRegistry.getPrimaryAddress();
+      if (newPrimary !== void 0) {
+        ilpInfo.ilpAddress = newPrimary;
+      }
+      if (autoCreatedConnector && autoCreatedConnector.removeRoute) {
+        autoCreatedConnector.removeRoute(removedAddress);
+      }
+      if (started && lastBootstrapResults.length > 0) {
+        void bootstrapServiceInstance.republish(lastBootstrapResults);
+      }
+    },
+    async claimPrefix(prefix, upstreamDestination, options) {
+      if (!started) {
+        throw new NodeError(
+          "Cannot claim prefix: node not started. Call start() first."
+        );
+      }
+      const prefixValidation = validatePrefix(prefix);
+      if (!prefixValidation.valid) {
+        throw new NodeError(
+          `Cannot claim prefix: ${prefixValidation.reason ?? "invalid prefix"}`
+        );
+      }
+      let claimAmount = options?.prefixPrice;
+      if (claimAmount === void 0) {
+        const peers = discoveryTrackerInstance.getAllDiscoveredPeers();
+        const upstreamPeer = peers.find(
+          (p) => p.peerInfo.ilpAddress === upstreamDestination || p.peerInfo.ilpAddresses && p.peerInfo.ilpAddresses.includes(upstreamDestination)
+        );
+        if (upstreamPeer?.peerInfo.prefixPricing?.basePrice) {
+          claimAmount = BigInt(upstreamPeer.peerInfo.prefixPricing.basePrice);
+        } else {
+          throw new NodeError(
+            "Cannot claim prefix: no amount provided and upstream peer prefix pricing not found in discovery"
+          );
+        }
+      }
+      const claimEvent = buildPrefixClaimEvent(
+        { requestedPrefix: prefix },
+        config.secretKey
+      );
+      return node.publishEvent(claimEvent, {
+        destination: upstreamDestination,
+        amount: claimAmount
+      });
     }
   };
   return node;
 }
+
+// src/workflow-orchestrator.ts
+import { buildJobRequestEvent, parseJobFeedback } from "@toon-protocol/core";
+var WorkflowOrchestrator = class {
+  node;
+  options;
+  state = "pending";
+  definition = null;
+  workflowEventId = "0".repeat(64);
+  customerPubkey = "0".repeat(64);
+  currentStepIndex = 0;
+  stepStates = [];
+  timeoutHandle = null;
+  processedResultIds = /* @__PURE__ */ new Set();
+  constructor(node, options) {
+    this.node = node;
+    this.options = {
+      stepTimeoutMs: 3e5,
+      // 5 minutes default
+      ...options
+    };
+    if (options?.workflowEventId) {
+      this.workflowEventId = options.workflowEventId;
+    }
+    if (options?.customerPubkey) {
+      this.customerPubkey = options.customerPubkey;
+    }
+  }
+  /**
+   * Returns the current workflow state.
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Returns per-step state tracking data (for testing/debugging).
+   */
+  getStepStates() {
+    return this.stepStates;
+  }
+  /**
+   * Starts a workflow: parses the definition, creates and publishes
+   * the Kind 5xxx job request for step 1, sets state to step_1_running.
+   */
+  async startWorkflow(definition) {
+    if (this.state !== "pending") {
+      throw new Error(
+        "WorkflowOrchestrator.startWorkflow() called on a non-pending orchestrator. Create a new WorkflowOrchestrator instance for each workflow."
+      );
+    }
+    if (!definition.steps || definition.steps.length === 0) {
+      throw new Error(
+        "WorkflowOrchestrator.startWorkflow() requires at least one step in the definition."
+      );
+    }
+    this.definition = definition;
+    this.stepStates = definition.steps.map((_, index) => ({
+      index,
+      settled: false
+    }));
+    if (this.options.eventStore) {
+      const now = this.options.now ? this.options.now() : Date.now();
+      const syntheticId = `wf${now.toString(16).padStart(16, "0")}${this.node.pubkey.slice(0, 48)}`;
+      const stateEvent = {
+        id: syntheticId.padEnd(64, "0").slice(0, 64),
+        pubkey: this.node.pubkey,
+        created_at: Math.floor(now / 1e3),
+        kind: 10040,
+        content: JSON.stringify({
+          state: "started",
+          definition
+        }),
+        tags: [],
+        sig: "0".repeat(128)
+      };
+      await this.options.eventStore.store(stateEvent);
+    }
+    await this.publishStepRequest(
+      0,
+      definition.initialInput.data,
+      definition.initialInput.type
+    );
+    this.state = "step_1_running";
+    this.currentStepIndex = 0;
+    this.startStepTimeout();
+  }
+  /**
+   * Handles a Kind 6xxx result event for the current step.
+   *
+   * If the current step matches, extracts the result content and either:
+   * - Advances to the next step (publishes Kind 5xxx for step N+1)
+   * - Marks workflow as completed (if this was the final step)
+   *
+   * Idempotent: re-processing a result for an already-advanced step is a no-op.
+   */
+  async handleStepResult(resultEvent) {
+    if (!this.definition) return;
+    if (resultEvent.kind < 6e3 || resultEvent.kind > 6999) return;
+    if (this.processedResultIds.has(resultEvent.id)) return;
+    const currentStep = this.stepStates[this.currentStepIndex];
+    if (!currentStep) return;
+    if (currentStep.resultEvent) return;
+    if (this.state === "completed" || this.state.endsWith("_failed")) return;
+    this.processedResultIds.add(resultEvent.id);
+    this.clearStepTimeout();
+    currentStep.resultEvent = resultEvent;
+    await this.settleStep(this.currentStepIndex, resultEvent);
+    if (this.options.eventStore) {
+      await this.options.eventStore.store(resultEvent);
+    }
+    const isLastStep = this.currentStepIndex === this.definition.steps.length - 1;
+    if (isLastStep) {
+      this.state = "completed";
+      await this.publishWorkflowNotification(
+        "success",
+        "Workflow completed successfully"
+      );
+    } else {
+      const nextIndex = this.currentStepIndex + 1;
+      const resultContent = resultEvent.content;
+      await this.publishStepRequest(nextIndex, resultContent, "text");
+      this.currentStepIndex = nextIndex;
+      this.state = `step_${nextIndex + 1}_running`;
+      this.startStepTimeout();
+    }
+  }
+  /**
+   * Handles a Kind 7000 feedback event for the current step.
+   *
+   * If the feedback status is 'error', marks the workflow as failed
+   * and notifies the customer.
+   */
+  async handleStepFeedback(feedbackEvent) {
+    if (!this.definition) return;
+    if (this.state === "completed" || this.state.endsWith("_failed")) return;
+    const parsed = parseJobFeedback(feedbackEvent);
+    if (!parsed) return;
+    if (parsed.status === "error") {
+      this.clearStepTimeout();
+      this.state = `step_${this.currentStepIndex + 1}_failed`;
+      if (this.options.eventStore) {
+        await this.options.eventStore.store(feedbackEvent);
+      }
+      await this.publishWorkflowNotification(
+        "error",
+        `Workflow failed at step ${this.currentStepIndex + 1}: ${parsed.content || "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Cleans up resources (timeout handles).
+   */
+  destroy() {
+    this.clearStepTimeout();
+  }
+  // ---------- Private Methods ----------
+  /**
+   * Publishes a Kind 5xxx job request for the given step.
+   */
+  async publishStepRequest(stepIndex, inputData, inputType) {
+    if (!this.definition) return;
+    const step = this.definition.steps[stepIndex];
+    if (!step) return;
+    const stepBid = this.getStepBid(stepIndex);
+    const jobRequest = buildJobRequestEvent(
+      {
+        kind: step.kind,
+        input: { data: inputData, type: inputType },
+        bid: stepBid,
+        output: "text/plain",
+        content: step.description,
+        targetProvider: step.targetProvider
+      },
+      this.getSecretKey()
+    );
+    const destination = this.options.destination ?? "g.toon.local";
+    await this.node.publishEvent(jobRequest, { destination });
+    const stepState = this.stepStates[stepIndex];
+    if (stepState) {
+      stepState.requestEventId = jobRequest.id;
+    }
+  }
+  /**
+   * Settles compute payment for a completed step.
+   */
+  async settleStep(stepIndex, resultEvent) {
+    if (!this.definition) return;
+    const stepState = this.stepStates[stepIndex];
+    if (!stepState || stepState.settled) return;
+    const step = this.definition.steps[stepIndex];
+    if (!step) return;
+    const providerIlpAddress = this.options.destination ?? "g.toon.provider";
+    try {
+      await this.node.settleCompute(resultEvent, providerIlpAddress, {
+        originalBid: this.getStepBid(stepIndex)
+      });
+      stepState.settled = true;
+    } catch (_err) {
+    }
+  }
+  /**
+   * Returns the bid allocation for a specific step.
+   * Uses explicit bidAllocation if set, otherwise proportional split.
+   */
+  getStepBid(stepIndex) {
+    if (!this.definition) return "0";
+    const step = this.definition.steps[stepIndex];
+    if (!step) return "0";
+    if (step.bidAllocation !== void 0) {
+      return step.bidAllocation;
+    }
+    try {
+      const totalBid = BigInt(this.definition.totalBid);
+      const stepCount = BigInt(this.definition.steps.length);
+      const perStep = totalBid / stepCount;
+      return perStep.toString();
+    } catch {
+      return "0";
+    }
+  }
+  /**
+   * Publishes a Kind 7000 workflow notification to the customer.
+   */
+  async publishWorkflowNotification(status, content) {
+    const destination = this.options.destination ?? "g.toon.local";
+    try {
+      await this.node.publishFeedback(
+        this.workflowEventId,
+        this.customerPubkey,
+        status,
+        content,
+        { destination }
+      );
+    } catch (_err) {
+    }
+  }
+  /**
+   * Starts a timeout timer for the current step.
+   */
+  startStepTimeout() {
+    this.clearStepTimeout();
+    const timeoutMs = this.options.stepTimeoutMs;
+    const timerFn = this.options.setTimer ?? setTimeout;
+    this.timeoutHandle = timerFn(() => {
+      this.state = `step_${this.currentStepIndex + 1}_failed`;
+      void this.publishWorkflowNotification(
+        "error",
+        `Workflow timed out at step ${this.currentStepIndex + 1} after ${timeoutMs}ms`
+      );
+    }, timeoutMs);
+  }
+  /**
+   * Returns the secret key for signing step events.
+   * Falls back to a deterministic key derived from the node pubkey
+   * (for testing -- production should always pass secretKey in options).
+   */
+  getSecretKey() {
+    if (this.options.secretKey) {
+      return this.options.secretKey;
+    }
+    throw new Error(
+      "WorkflowOrchestrator requires secretKey in options to sign step events"
+    );
+  }
+  /**
+   * Clears the current step timeout.
+   */
+  clearStepTimeout() {
+    if (this.timeoutHandle !== null) {
+      const cancelFn = this.options.clearTimer ?? clearTimeout;
+      cancelFn(this.timeoutHandle);
+      this.timeoutHandle = null;
+    }
+  }
+};
+
+// src/swarm-coordinator.ts
+import {
+  ToonError as ToonError3,
+  parseSwarmRequest,
+  parseSwarmSelection
+} from "@toon-protocol/core";
+var SwarmCoordinator = class {
+  node;
+  options;
+  state = "collecting";
+  swarmRequestId = "";
+  customerPubkey = "";
+  maxProviders = 0;
+  submissions = [];
+  timeoutHandle = null;
+  started = false;
+  settlementSucceeded = false;
+  submissionIds = /* @__PURE__ */ new Set();
+  constructor(node, options) {
+    this.node = node;
+    this.options = {
+      timeoutMs: 6e5,
+      // 10 minutes default
+      ...options
+    };
+  }
+  /**
+   * Returns the current swarm state.
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Returns whether settlement was successfully completed.
+   * Only meaningful when state is 'settled' (returns true).
+   * If settlement fails, the state remains 'judging' and this returns false.
+   */
+  isSettlementSucceeded() {
+    return this.settlementSucceeded;
+  }
+  /**
+   * Returns the collected eligible submissions.
+   */
+  getSubmissions() {
+    return this.submissions;
+  }
+  /**
+   * Starts a swarm: parses the swarm request, initializes collection,
+   * and starts the timeout timer.
+   */
+  async startSwarm(swarmRequest) {
+    const parsed = parseSwarmRequest(swarmRequest);
+    if (!parsed) {
+      throw new ToonError3(
+        "Invalid swarm request event: missing swarm tag or invalid Kind 5xxx",
+        "DVM_INVALID_KIND"
+      );
+    }
+    this.swarmRequestId = swarmRequest.id;
+    this.customerPubkey = swarmRequest.pubkey;
+    this.maxProviders = parsed.maxProviders;
+    this.state = "collecting";
+    this.submissions = [];
+    this.submissionIds = /* @__PURE__ */ new Set();
+    this.started = true;
+    if (this.options.eventStore) {
+      await this.options.eventStore.store(swarmRequest);
+    }
+    this.startTimeout();
+  }
+  /**
+   * Handles a Kind 6xxx result event (provider submission).
+   *
+   * Validates the `e` tag references the swarm request, adds to the
+   * submissions list, and checks if max providers is reached.
+   *
+   * Late submissions (after timeout or max reached) are ignored.
+   * Submissions before startSwarm() are silently ignored.
+   */
+  async handleSubmission(resultEvent) {
+    if (!this.started) return;
+    if (this.state !== "collecting") return;
+    if (resultEvent.kind < 6e3 || resultEvent.kind > 6999) return;
+    const eTag = resultEvent.tags.find((t) => t[0] === "e");
+    if (!eTag) return;
+    const requestEventId = eTag[1];
+    if (requestEventId === void 0 || requestEventId !== this.swarmRequestId)
+      return;
+    if (this.submissionIds.has(resultEvent.id)) return;
+    this.submissionIds.add(resultEvent.id);
+    this.submissions.push(resultEvent);
+    if (this.options.eventStore) {
+      await this.options.eventStore.store(resultEvent);
+    }
+    if (this.submissions.length >= this.maxProviders) {
+      this.clearTimeout();
+      this.state = "judging";
+    }
+  }
+  /**
+   * Selects the winner and settles compute payment.
+   *
+   * Validates:
+   * - Swarm is in `judging` state (not `collecting`, `settled`, or `failed`)
+   * - Selection references a submission in the collected set
+   * - Swarm has not already been settled (idempotency guard)
+   *
+   * @throws ToonError with code DVM_SWARM_ALREADY_SETTLED if already settled
+   * @throws ToonError with code DVM_SWARM_INVALID_SELECTION if winner not in submissions
+   */
+  async selectWinner(selectionEvent) {
+    if (this.state === "settled") {
+      throw new ToonError3(
+        "Swarm has already been settled; duplicate selection rejected",
+        "DVM_SWARM_ALREADY_SETTLED"
+      );
+    }
+    if (this.state !== "judging") {
+      throw new ToonError3(
+        `Cannot select winner in state '${this.state}'; swarm must be in 'judging' state`,
+        "DVM_SWARM_INVALID_SELECTION"
+      );
+    }
+    if (selectionEvent.pubkey !== this.customerPubkey) {
+      throw new ToonError3(
+        "Selection event pubkey does not match the swarm request customer pubkey",
+        "DVM_SWARM_INVALID_SELECTION"
+      );
+    }
+    const parsed = parseSwarmSelection(selectionEvent);
+    if (!parsed) {
+      throw new ToonError3(
+        "Invalid swarm selection event: missing winner tag or invalid Kind 7000",
+        "DVM_SWARM_INVALID_SELECTION"
+      );
+    }
+    if (parsed.swarmRequestEventId !== this.swarmRequestId) {
+      throw new ToonError3(
+        `Selection event references swarm '${parsed.swarmRequestEventId}' but this swarm is '${this.swarmRequestId}'`,
+        "DVM_SWARM_INVALID_SELECTION"
+      );
+    }
+    const winnerSubmission = this.submissions.find(
+      (s) => s.id === parsed.winnerResultEventId
+    );
+    if (!winnerSubmission) {
+      throw new ToonError3(
+        `Winner result event ID '${parsed.winnerResultEventId}' not found in collected submissions`,
+        "DVM_SWARM_INVALID_SELECTION"
+      );
+    }
+    const providerIlpAddress = this.options.destination ?? "g.toon.provider";
+    try {
+      await this.node.settleCompute(winnerSubmission, providerIlpAddress);
+      this.settlementSucceeded = true;
+    } catch (_err) {
+      this.settlementSucceeded = false;
+      throw new ToonError3(
+        "Settlement failed for winning provider; swarm remains in judging state for retry",
+        "DVM_SWARM_SETTLEMENT_FAILED"
+      );
+    }
+    if (this.options.eventStore) {
+      await this.options.eventStore.store(selectionEvent);
+    }
+    this.state = "settled";
+  }
+  /**
+   * Cleans up resources (timeout handles).
+   */
+  destroy() {
+    this.clearTimeout();
+  }
+  // ---------- Private Methods ----------
+  /**
+   * Starts the collection timeout timer.
+   */
+  startTimeout() {
+    this.clearTimeout();
+    const timeoutMs = this.options.timeoutMs;
+    const timerFn = this.options.setTimer ?? setTimeout;
+    this.timeoutHandle = timerFn(() => {
+      if (this.state !== "collecting") return;
+      if (this.submissions.length === 0) {
+        this.state = "failed";
+        void this.publishNoSubmissionsFeedback();
+      } else {
+        this.state = "judging";
+      }
+    }, timeoutMs);
+  }
+  /**
+   * Publishes a Kind 7000 feedback event indicating no submissions were received.
+   */
+  async publishNoSubmissionsFeedback() {
+    const destination = this.options.destination ?? "g.toon.local";
+    try {
+      await this.node.publishFeedback(
+        this.swarmRequestId,
+        this.customerPubkey,
+        "error",
+        "Swarm timed out with no submissions",
+        { destination }
+      );
+    } catch (_err) {
+    }
+  }
+  /**
+   * Clears the current timeout timer.
+   */
+  clearTimeout() {
+    if (this.timeoutHandle !== null) {
+      const cancelFn = this.options.clearTimer ?? clearTimeout;
+      cancelFn(this.timeoutHandle);
+      this.timeoutHandle = null;
+    }
+  }
+};
+
+// src/prefix-claim-handler.ts
+import {
+  parsePrefixClaimEvent,
+  buildPrefixGrantEvent,
+  validatePrefix as validatePrefix2
+} from "@toon-protocol/core";
+function createPrefixClaimHandler(options) {
+  return async (ctx) => {
+    const event = ctx.decode();
+    const claim = parsePrefixClaimEvent(event);
+    if (!claim) {
+      return ctx.reject("F06", "Invalid prefix claim event: malformed content");
+    }
+    const validation = validatePrefix2(claim.requestedPrefix);
+    if (!validation.valid) {
+      return ctx.reject(
+        "F06",
+        `Invalid prefix: ${validation.reason ?? "unknown validation error"}`
+      );
+    }
+    if (ctx.amount < options.prefixPricing.basePrice) {
+      return ctx.reject(
+        "F06",
+        `Insufficient payment: received ${ctx.amount}, required ${options.prefixPricing.basePrice}`
+      );
+    }
+    const claimedPrefixes = options.getClaimedPrefixes();
+    if (claimedPrefixes.has(claim.requestedPrefix)) {
+      return ctx.reject(
+        "F06",
+        `PREFIX_TAKEN: prefix "${claim.requestedPrefix}" is already claimed`
+      );
+    }
+    const claimed = options.claimPrefix(claim.requestedPrefix, event.pubkey);
+    if (!claimed) {
+      return ctx.reject(
+        "F06",
+        `PREFIX_TAKEN: prefix "${claim.requestedPrefix}" is already claimed`
+      );
+    }
+    const prefix = options.ilpAddressPrefix ?? "g.toon";
+    const ilpAddress = `${prefix}.${claim.requestedPrefix}`;
+    const grantEvent = buildPrefixGrantEvent(
+      {
+        grantedPrefix: claim.requestedPrefix,
+        claimerPubkey: event.pubkey,
+        ilpAddress
+      },
+      options.secretKey
+    );
+    await options.publishGrant(grantEvent);
+    return ctx.accept();
+  };
+}
+
+// src/arweave/arweave-dvm-handler.ts
+import { parseBlobStorageRequest } from "@toon-protocol/core";
+var MIME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9!#$&\-^_.+]*\/[a-zA-Z0-9][a-zA-Z0-9!#$&\-^_.+]*$/;
+function sanitizeContentType(contentType) {
+  const base = (contentType.split(";")[0] ?? "").trim();
+  if (base.length > 0 && base.length <= 255 && MIME_REGEX.test(base)) {
+    return base;
+  }
+  return "application/octet-stream";
+}
+function createArweaveDvmHandler(config) {
+  const { turboAdapter, chunkManager, arweaveTags } = config;
+  return async (ctx) => {
+    const event = ctx.decode();
+    const parsed = parseBlobStorageRequest(event);
+    if (!parsed) {
+      return {
+        accept: false,
+        code: "F00",
+        message: "Malformed kind:5094 blob storage request"
+      };
+    }
+    const uploadTags = {
+      ...arweaveTags,
+      "Content-Type": sanitizeContentType(parsed.contentType)
+    };
+    if (parsed.uploadId !== void 0 && parsed.chunkIndex !== void 0 && parsed.totalChunks !== void 0) {
+      try {
+        const result = chunkManager.addChunk(
+          parsed.uploadId,
+          parsed.chunkIndex,
+          parsed.totalChunks,
+          parsed.blobData
+        );
+        if (!result.complete) {
+          return {
+            accept: true,
+            data: Buffer.from(`ack:${parsed.chunkIndex}`).toString("base64")
+          };
+        }
+        const assembled = result.assembled ?? Buffer.alloc(0);
+        const { txId } = await turboAdapter.upload(assembled, uploadTags);
+        return {
+          accept: true,
+          data: Buffer.from(txId).toString("base64")
+        };
+      } catch (error) {
+        const internalMsg = error instanceof Error ? error.message : "Unknown chunk error";
+        const safeMsg = internalMsg.includes("Duplicate chunkIndex") ? "Duplicate chunk rejected" : internalMsg.includes("Max active uploads") ? "Server busy, too many concurrent uploads" : internalMsg.includes("exceeds max bytes") ? "Upload size limit exceeded" : "Chunk processing error";
+        return {
+          accept: false,
+          code: "F00",
+          message: safeMsg
+        };
+      }
+    }
+    try {
+      const { txId } = await turboAdapter.upload(parsed.blobData, uploadTags);
+      return {
+        accept: true,
+        data: Buffer.from(txId).toString("base64")
+      };
+    } catch {
+      return {
+        accept: false,
+        code: "T00",
+        message: "Arweave upload failed"
+      };
+    }
+  };
+}
+
+// src/arweave/turbo-adapter.ts
+import { Readable } from "stream";
+var TurboUploadAdapter = class {
+  turboClient;
+  initialized = false;
+  constructor(turboClient) {
+    if (turboClient) {
+      this.turboClient = turboClient;
+      this.initialized = true;
+    }
+  }
+  async getClient() {
+    if (!this.initialized) {
+      const { TurboFactory } = await import("@ardrive/turbo-sdk/node");
+      const Arweave = (await import("./node-WPA2UDEH.js")).default;
+      const arweave = Arweave.init({});
+      const jwk = await arweave.crypto.generateJWK();
+      this.turboClient = TurboFactory.authenticated({ privateKey: jwk });
+      this.initialized = true;
+    }
+    return this.turboClient;
+  }
+  async upload(data, tags) {
+    const client = await this.getClient();
+    const tagArray = [];
+    if (tags) {
+      for (const [name, value] of Object.entries(tags)) {
+        tagArray.push({ name, value });
+      }
+    }
+    const result = await client.uploadFile({
+      fileStreamFactory: () => Readable.from(data),
+      fileSizeFactory: () => data.length,
+      ...tagArray.length > 0 ? { dataItemOpts: { tags: tagArray } } : {}
+    });
+    return { txId: result.id };
+  }
+};
+
+// src/arweave/chunk-manager.ts
+var ChunkManager = class {
+  uploads = /* @__PURE__ */ new Map();
+  timeoutMs;
+  maxActiveUploads;
+  maxBytesPerUpload;
+  constructor(config = {}) {
+    this.timeoutMs = config.timeoutMs ?? 3e5;
+    this.maxActiveUploads = config.maxActiveUploads ?? 100;
+    this.maxBytesPerUpload = config.maxBytesPerUpload ?? 50 * 1024 * 1024;
+  }
+  /**
+   * Add a chunk for a given uploadId.
+   *
+   * @param uploadId - Unique identifier for the upload session.
+   * @param chunkIndex - Zero-based index of this chunk.
+   * @param totalChunks - Total number of chunks expected.
+   * @param data - The chunk data.
+   * @returns Result indicating completion status or error.
+   * @throws Error if memory cap reached or duplicate chunk.
+   */
+  addChunk(uploadId, chunkIndex, totalChunks, data) {
+    let state = this.uploads.get(uploadId);
+    if (!state) {
+      if (this.uploads.size >= this.maxActiveUploads) {
+        throw new Error(
+          `Max active uploads reached (${this.maxActiveUploads}). Cannot accept new uploadId.`
+        );
+      }
+      const timer = setTimeout(() => {
+        this.cleanup(uploadId);
+      }, this.timeoutMs);
+      state = {
+        chunks: /* @__PURE__ */ new Map(),
+        totalChunks,
+        timer
+      };
+      this.uploads.set(uploadId, state);
+    }
+    if (chunkIndex < 0 || chunkIndex >= state.totalChunks) {
+      throw new Error(
+        `chunkIndex ${chunkIndex} out of bounds for totalChunks ${state.totalChunks} (uploadId ${uploadId})`
+      );
+    }
+    if (state.chunks.has(chunkIndex)) {
+      throw new Error(
+        `Duplicate chunkIndex ${chunkIndex} for uploadId ${uploadId}`
+      );
+    }
+    let currentBytes = 0;
+    for (const chunk of state.chunks.values()) {
+      currentBytes += chunk.length;
+    }
+    if (currentBytes + data.length > this.maxBytesPerUpload) {
+      this.cleanup(uploadId);
+      throw new Error(
+        `Upload ${uploadId} exceeds max bytes per upload (${this.maxBytesPerUpload})`
+      );
+    }
+    state.chunks.set(chunkIndex, data);
+    if (state.chunks.size === state.totalChunks) {
+      const orderedChunks = [];
+      for (let i = 0; i < state.totalChunks; i++) {
+        const chunk = state.chunks.get(i);
+        if (!chunk) {
+          throw new Error(`Missing chunk ${i} for upload`);
+        }
+        orderedChunks.push(chunk);
+      }
+      const assembled = Buffer.concat(orderedChunks);
+      this.cleanup(uploadId);
+      return { complete: true, assembled };
+    }
+    return { complete: false };
+  }
+  /**
+   * Check if an upload is complete (all chunks received).
+   * Returns false if the uploadId is unknown (cleaned up or never started).
+   */
+  isComplete(uploadId) {
+    const state = this.uploads.get(uploadId);
+    if (!state) return false;
+    return state.chunks.size === state.totalChunks;
+  }
+  /**
+   * Clean up state for a given uploadId, clearing the timeout timer.
+   */
+  cleanup(uploadId) {
+    const state = this.uploads.get(uploadId);
+    if (state) {
+      clearTimeout(state.timer);
+      this.uploads.delete(uploadId);
+    }
+  }
+  /**
+   * Clean up all active uploads and their timers.
+   * Call this on node shutdown to prevent timer leaks.
+   */
+  destroyAll() {
+    for (const [, state] of this.uploads) {
+      clearTimeout(state.timer);
+    }
+    this.uploads.clear();
+  }
+};
+
+// src/arweave/chunked-upload.ts
+import { randomUUID } from "crypto";
+import { buildBlobStorageRequest } from "@toon-protocol/core";
+async function uploadBlob(node, blob, destination, options) {
+  const contentType = options.contentType ?? "application/octet-stream";
+  const pricePerByte = options.pricePerByte ?? 10n;
+  const amount = BigInt(blob.length) * pricePerByte;
+  const event = buildBlobStorageRequest(
+    {
+      blobData: blob,
+      contentType,
+      bid: amount.toString()
+    },
+    options.secretKey
+  );
+  const result = await node.publishEvent(event, { destination, amount });
+  if (!result.success) {
+    throw new Error(`Blob upload failed: ${result.message ?? "unknown error"}`);
+  }
+  if (result.data) {
+    return Buffer.from(result.data, "base64").toString("utf-8");
+  }
+  return result.eventId;
+}
+async function uploadBlobChunked(node, blob, destination, options) {
+  if (blob.length === 0) {
+    throw new Error("Cannot upload empty blob via chunked upload");
+  }
+  const chunkSize = options.chunkSize ?? 5e5;
+  const contentType = options.contentType ?? "application/octet-stream";
+  const pricePerByte = options.pricePerByte ?? 10n;
+  const uploadId = randomUUID();
+  const totalChunks = Math.ceil(blob.length / chunkSize);
+  let lastResult;
+  for (let i = 0; i < totalChunks; i++) {
+    const start = i * chunkSize;
+    const end = Math.min(start + chunkSize, blob.length);
+    const chunkData = blob.subarray(start, end);
+    const amount = BigInt(chunkData.length) * pricePerByte;
+    const event = buildBlobStorageRequest(
+      {
+        blobData: Buffer.from(chunkData),
+        contentType,
+        bid: amount.toString(),
+        params: [
+          { key: "uploadId", value: uploadId },
+          { key: "chunkIndex", value: String(i) },
+          { key: "totalChunks", value: String(totalChunks) }
+        ]
+      },
+      options.secretKey
+    );
+    lastResult = await node.publishEvent(event, { destination, amount });
+    if (!lastResult.success) {
+      throw new Error(
+        `Chunk ${i}/${totalChunks} upload failed: ${lastResult.message ?? "unknown error"}`
+      );
+    }
+  }
+  if (!lastResult) {
+    throw new Error("No chunks were uploaded");
+  }
+  if (lastResult.data) {
+    return Buffer.from(lastResult.data, "base64").toString("utf-8");
+  }
+  return lastResult.eventId;
+}
 export {
+  ChunkManager,
   HandlerError,
   HandlerRegistry,
   IdentityError,
   NodeError,
   PricingError,
+  SwarmCoordinator,
+  TurboUploadAdapter,
   VerificationError,
+  WorkflowOrchestrator,
   buildSkillDescriptor,
+  createArweaveDvmHandler,
   createEventStorageHandler,
   createHandlerContext,
   createNode,
   createPaymentHandlerBridge,
+  createPrefixClaimHandler,
   createPricingValidator,
   createVerificationPipeline,
   fromMnemonic,
   fromSecretKey,
-  generateMnemonic
+  generateMnemonic,
+  uploadBlob,
+  uploadBlobChunked
 };
 //# sourceMappingURL=index.js.map