@unicitylabs/sphere-sdk 0.16.0 → 0.17.1

package/dist/modules/payments-v2/index.js

@@ -137,6 +137,135 @@ var STORE_KEYS = {
   knownSpends: "known-spends"
 };
 
+// core/errors.ts
+var SphereError = class extends Error {
+  code;
+  cause;
+  /**
+   * #441 deferred-paid linkage: the transferId of the possibly-committed send,
+   * stamped by `sendOnce` before the error leaves so a payment-request consumer
+   * can durably journal request→transfer and resolve 'paid' only when that
+   * transfer actually completes (never optimistically). Present ONLY on
+   * possibly-committed outcomes ({@link isPossiblyCommittedSendOutcome}).
+   */
+  transferId;
+  constructor(message, code, cause) {
+    super(message);
+    this.name = "SphereError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+var PartialSendConflictError = class extends SphereError {
+  /**
+   * The FIRST partial attempt's transferId — its intent stays open for resume,
+   * and it is the §6 handoff anchor. NOTE: `send()` may re-plan the remainder across
+   * SEVERAL internal attempts before giving up, so {@link committedTokenIds} can
+   * span MULTIPLE transferIds — they do NOT all map to this single id.
+   */
+  transferId;
+  /**
+   * Source token ids whose spend already certified on-chain (and whose finished
+   * output blob is journaled for delivery). Their value has already been
+   * delivered; NEVER re-send these. May accumulate across several internal
+   * remainder-re-plan attempts (so not all are journaled under {@link transferId}).
+   */
+  committedTokenIds;
+  /**
+   * The still-undelivered portion (base units, decimal string) — `send()` could
+   * not COMPLETE it from the remaining live sources (insufficient funds or a
+   * transient error; see `cause`). Re-plan ONLY this amount, under a new
+   * transferId; the delivered legs converge via the recipient's §6 claim.
+   */
+  remainingAmount;
+  constructor(message, transferId, committedTokenIds, remainingAmount, cause) {
+    super(message, "SEND_PARTIALLY_COMPLETED", cause);
+    this.name = "PartialSendConflictError";
+    this.transferId = transferId;
+    this.committedTokenIds = [...committedTokenIds];
+    this.remainingAmount = remainingAmount;
+  }
+};
+var POSSIBLY_COMMITTED_SEND_CODES = /* @__PURE__ */ new Set([
+  "SEND_SYNC_PENDING",
+  "CERTIFICATION_UNCONFIRMED",
+  "CHECKPOINT_PERSIST_FAILED",
+  "SPLIT_CHECKPOINT_LOST",
+  "CHECKPOINT_TRUSTBASE_MISMATCH",
+  "SEND_PARTIALLY_COMPLETED"
+]);
+function isPossiblyCommittedSendOutcome(err) {
+  return isSphereError(err) && POSSIBLY_COMMITTED_SEND_CODES.has(err.code);
+}
+function isSphereError(err) {
+  return err instanceof SphereError;
+}
+
+// core/uuid.ts
+function randomUUID() {
+  const c = globalThis.crypto;
+  if (typeof c !== "undefined" && typeof c.randomUUID === "function") {
+    return c.randomUUID();
+  }
+  const b = c.getRandomValues(new Uint8Array(16));
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  const h = Array.from(b, (x) => x.toString(16).padStart(2, "0"));
+  return `${h[0]}${h[1]}${h[2]}${h[3]}-${h[4]}${h[5]}-${h[6]}${h[7]}-${h[8]}${h[9]}-${h[10]}${h[11]}${h[12]}${h[13]}${h[14]}${h[15]}`;
+}
+
+// modules/payments-v2/async.ts
+var SingleFlight = class {
+  flight = null;
+  run(fn) {
+    if (this.flight !== null) return this.flight;
+    const current = fn().finally(() => {
+      this.flight = null;
+    });
+    this.flight = current;
+    return current;
+  }
+};
+var SerialChain = class {
+  tail = Promise.resolve();
+  /** FIFO; starts after every prior fn settled; returns this fn's own outcome. */
+  enqueue(fn) {
+    const run = this.tail.then(fn, fn);
+    this.tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+};
+function coalesced(run, observe) {
+  let inFlight = false;
+  let queued = false;
+  const start = () => {
+    inFlight = true;
+    let running;
+    try {
+      running = run();
+    } catch {
+      running = Promise.resolve();
+    }
+    observe?.(running);
+    void running.catch(() => void 0).finally(() => {
+      inFlight = false;
+      if (!queued) return;
+      queued = false;
+      start();
+    });
+  };
+  return () => {
+    if (inFlight) {
+      queued = true;
+      return;
+    }
+    start();
+  };
+}
+
 // node_modules/@noble/hashes/utils.js
 function isBytes(a) {
   return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array" && "BYTES_PER_ELEMENT" in a && a.BYTES_PER_ELEMENT === 1;
@@ -464,72 +593,6 @@ var sha256 = /* @__PURE__ */ createHasher(
 // core/crypto.ts
 import * as bip39 from "bip39";
 import CryptoJS from "crypto-js";
-
-// core/errors.ts
-var SphereError = class extends Error {
-  code;
-  cause;
-  /**
-   * #441 deferred-paid linkage: the transferId of the possibly-committed send,
-   * stamped by `sendOnce` before the error leaves so a payment-request consumer
-   * can durably journal request→transfer and resolve 'paid' only when that
-   * transfer actually completes (never optimistically). Present ONLY on
-   * possibly-committed outcomes ({@link isPossiblyCommittedSendOutcome}).
-   */
-  transferId;
-  constructor(message, code, cause) {
-    super(message);
-    this.name = "SphereError";
-    this.code = code;
-    this.cause = cause;
-  }
-};
-var PartialSendConflictError = class extends SphereError {
-  /**
-   * The FIRST partial attempt's transferId — its intent stays open for resume,
-   * and it is the §6 handoff anchor. NOTE: `send()` may re-plan the remainder across
-   * SEVERAL internal attempts before giving up, so {@link committedTokenIds} can
-   * span MULTIPLE transferIds — they do NOT all map to this single id.
-   */
-  transferId;
-  /**
-   * Source token ids whose spend already certified on-chain (and whose finished
-   * output blob is journaled for delivery). Their value has already been
-   * delivered; NEVER re-send these. May accumulate across several internal
-   * remainder-re-plan attempts (so not all are journaled under {@link transferId}).
-   */
-  committedTokenIds;
-  /**
-   * The still-undelivered portion (base units, decimal string) — `send()` could
-   * not COMPLETE it from the remaining live sources (insufficient funds or a
-   * transient error; see `cause`). Re-plan ONLY this amount, under a new
-   * transferId; the delivered legs converge via the recipient's §6 claim.
-   */
-  remainingAmount;
-  constructor(message, transferId, committedTokenIds, remainingAmount, cause) {
-    super(message, "SEND_PARTIALLY_COMPLETED", cause);
-    this.name = "PartialSendConflictError";
-    this.transferId = transferId;
-    this.committedTokenIds = [...committedTokenIds];
-    this.remainingAmount = remainingAmount;
-  }
-};
-var POSSIBLY_COMMITTED_SEND_CODES = /* @__PURE__ */ new Set([
-  "SEND_SYNC_PENDING",
-  "CERTIFICATION_UNCONFIRMED",
-  "CHECKPOINT_PERSIST_FAILED",
-  "SPLIT_CHECKPOINT_LOST",
-  "CHECKPOINT_TRUSTBASE_MISMATCH",
-  "SEND_PARTIALLY_COMPLETED"
-]);
-function isPossiblyCommittedSendOutcome(err) {
-  return isSphereError(err) && POSSIBLY_COMMITTED_SEND_CODES.has(err.code);
-}
-function isSphereError(err) {
-  return err instanceof SphereError;
-}
-
-// core/crypto.ts
 var CURVE_ORDER = BigInt(
   "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141"
 );
@@ -544,71 +607,6 @@ function bytesToHex(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
-// core/uuid.ts
-function randomUUID() {
-  const c = globalThis.crypto;
-  if (typeof c !== "undefined" && typeof c.randomUUID === "function") {
-    return c.randomUUID();
-  }
-  const b = c.getRandomValues(new Uint8Array(16));
-  b[6] = b[6] & 15 | 64;
-  b[8] = b[8] & 63 | 128;
-  const h = Array.from(b, (x) => x.toString(16).padStart(2, "0"));
-  return `${h[0]}${h[1]}${h[2]}${h[3]}-${h[4]}${h[5]}-${h[6]}${h[7]}-${h[8]}${h[9]}-${h[10]}${h[11]}${h[12]}${h[13]}${h[14]}${h[15]}`;
-}
-
-// modules/payments-v2/async.ts
-var SingleFlight = class {
-  flight = null;
-  run(fn) {
-    if (this.flight !== null) return this.flight;
-    const current = fn().finally(() => {
-      this.flight = null;
-    });
-    this.flight = current;
-    return current;
-  }
-};
-var SerialChain = class {
-  tail = Promise.resolve();
-  /** FIFO; starts after every prior fn settled; returns this fn's own outcome. */
-  enqueue(fn) {
-    const run = this.tail.then(fn, fn);
-    this.tail = run.then(
-      () => void 0,
-      () => void 0
-    );
-    return run;
-  }
-};
-function coalesced(run, observe) {
-  let inFlight = false;
-  let queued = false;
-  const start = () => {
-    inFlight = true;
-    let running;
-    try {
-      running = run();
-    } catch {
-      running = Promise.resolve();
-    }
-    observe?.(running);
-    void running.catch(() => void 0).finally(() => {
-      inFlight = false;
-      if (!queued) return;
-      queued = false;
-      start();
-    });
-  };
-  return () => {
-    if (inFlight) {
-      queued = true;
-      return;
-    }
-    start();
-  };
-}
-
 // modules/payments-v2/machine/journal.ts
 var MAX_DELIVERY_ATTEMPTS = 6;
 var RATE_LIMIT_DEFER_MS = 3e4;
@@ -787,6 +785,17 @@ function createMachineStores(kv) {
   };
 }
 
+// modules/payments-v2/machine/payload-view.ts
+function isWholeIntent(p) {
+  return p.kind === "whole" || p.kind === "coinless";
+}
+function splitOf(p) {
+  return p.kind === "coin" ? p.split : void 0;
+}
+function coinIdOf(p) {
+  return p.kind === "coin" ? p.coinId : void 0;
+}
+
 // token-engine/errors.ts
 var TransferConflictError = class extends SphereError {
   /**
@@ -1028,13 +1037,14 @@ var TransferMachine = class {
       const finished = await engine.transfer({ token: source, recipientPubkey }, opts);
       return { recipientBlob: finished.blob.token };
     }
-    const split = ctx.payload.split;
+    const split = splitOf(ctx.payload);
+    const splitCoinId = coinIdOf(ctx.payload);
     const { outputs } = await engine.split(
       {
         token: source,
         outputs: [
-          { recipientPubkey, coinId: ctx.payload.coinId, amount: BigInt(split.splitAmount) },
-          { recipientPubkey: this.deps.ownPubkey, coinId: ctx.payload.coinId, amount: BigInt(split.remainderAmount) }
+          { recipientPubkey, coinId: splitCoinId, amount: BigInt(split.splitAmount) },
+          { recipientPubkey: this.deps.ownPubkey, coinId: splitCoinId, amount: BigInt(split.remainderAmount) }
         ]
       },
       opts
@@ -1156,7 +1166,9 @@ var TransferMachine = class {
     const entry = {
       transferId: r.transferId,
       remainingAmount: undelivered.toString(),
-      coinId: r.payload.coinId,
+      // '' only on a token-addressed intent, which is one leg: it either lands or
+      // conflicts, so a shortfall row is unreachable there (settlePartial needs >1).
+      coinId: coinIdOf(r.payload) ?? "",
       recipient: r.payload.recipient,
       committedTokenIds: committed.map((o) => o.op.sourceTokenId),
       createdAt: this.deps.now()
@@ -1182,8 +1194,16 @@ var TransferMachine = class {
   }
   async finishBookkeeping(engine, transferId, payload, phase, committed) {
     try {
-      const committedAmount = await this.settledAmount(engine, payload.coinId, committed);
-      await this.deps.recordHistory?.({ transferId, payload, phase, committedAmount });
+      const coinId = coinIdOf(payload);
+      const committedAmount = coinId === void 0 ? "0" : await this.settledAmount(engine, coinId, committed);
+      const committedAssets = coinId === void 0 ? await this.settledAssets(engine, committed) : void 0;
+      await this.deps.recordHistory?.({
+        transferId,
+        payload,
+        phase,
+        committedAmount,
+        ...committedAssets !== void 0 ? { committedAssets } : {}
+      });
     } catch {
     }
     try {
@@ -1197,6 +1217,18 @@ var TransferMachine = class {
    * a journal-rehydrated resume leg has no source token, but every committed
    * leg carries its recipient blob, so the outcome-derived rule is uniform).
    */
+  /** Every asset across the certified recipient blobs — the whole-spend twin of settledAmount. */
+  async settledAssets(engine, committed) {
+    const total = /* @__PURE__ */ new Map();
+    for (const outcome of committed) {
+      if (outcome.recipientBlob === void 0) continue;
+      const token = await engine.decodeToken({ tokenId: "", token: outcome.recipientBlob });
+      for (const asset of engine.readValue(token)?.assets ?? []) {
+        total.set(asset.coinId, (total.get(asset.coinId) ?? 0n) + asset.amount);
+      }
+    }
+    return [...total].map(([coinId, amount]) => ({ coinId, amount: amount.toString() }));
+  }
   async settledAmount(engine, coinId, committed) {
     let total = 0n;
     for (const outcome of committed) {
@@ -1225,8 +1257,11 @@ var TransferMachine = class {
   }
 };
 function conflictAmount(engine, payload, op, source) {
-  if (op.kind === "split") return BigInt(payload.split.splitAmount);
-  return source !== void 0 ? engine.balanceOf(source, payload.coinId) : 0n;
+  const split = splitOf(payload);
+  if (op.kind === "split") return BigInt(split.splitAmount);
+  const coinId = coinIdOf(payload);
+  if (coinId === void 0) return 0n;
+  return source !== void 0 ? engine.balanceOf(source, coinId) : 0n;
 }
 
 // modules/payments-v2/machine/resume.ts
@@ -1333,6 +1368,14 @@ async function runOne(ctx, job, report) {
       report.failed.push(job.transferId);
       return;
     }
+    if (isWholeIntent(job.payload) && token.valueEnvelope === "bare_collection") {
+      logger.warn(
+        "PaymentsV2",
+        `resume: token intent ${job.transferId} names a source carrying coin value \u2014 refusing`
+      );
+      report.failed.push(job.transferId);
+      return;
+    }
     mine.set(op.sourceTokenId, token);
   }
   try {
@@ -1363,6 +1406,28 @@ async function classifyResumeFailure(deps, stores, transferId, err, report) {
   }
   report.failed.push(transferId);
 }
+function validateCoinPayload(c) {
+  if (typeof c.coinId !== "string" || typeof c.amount !== "string") {
+    throw new SphereError("intent payload is missing coinId/amount", "VALIDATION_ERROR");
+  }
+  const s = c.split;
+  if (s !== void 0 && (typeof s.tokenId !== "string" || typeof s.splitAmount !== "string" || typeof s.remainderAmount !== "string")) {
+    throw new SphereError("intent payload split spec is malformed", "VALIDATION_ERROR");
+  }
+  return { ...c, kind: "coin" };
+}
+function validateWholePayload(p) {
+  if (p.direct?.length !== 1 || typeof p.direct[0] !== "string" || p.direct[0] === "") {
+    throw new SphereError(
+      "token intent payload must name exactly one source token",
+      "VALIDATION_ERROR"
+    );
+  }
+  if (p.split !== void 0) {
+    throw new SphereError("token intent payload cannot carry a split", "VALIDATION_ERROR");
+  }
+  return { ...p, kind: "whole", direct: [p.direct[0]] };
+}
 function validatePayload(raw) {
   const p = raw !== null && typeof raw === "object" ? raw : null;
   if (p === null || p.v !== 2 || !Array.isArray(p.direct) || p.direct.some((t) => typeof t !== "string")) {
@@ -1371,14 +1436,17 @@ function validatePayload(raw) {
       "VALIDATION_ERROR"
     );
   }
-  if (typeof p.recipient !== "string" || typeof p.coinId !== "string" || typeof p.amount !== "string") {
-    throw new SphereError("intent payload is missing recipient/coinId/amount", "VALIDATION_ERROR");
+  if (typeof p.recipient !== "string") {
+    throw new SphereError("intent payload is missing recipient", "VALIDATION_ERROR");
   }
-  const s = p.split;
-  if (s !== void 0 && (typeof s.tokenId !== "string" || typeof s.splitAmount !== "string" || typeof s.remainderAmount !== "string")) {
-    throw new SphereError("intent payload split spec is malformed", "VALIDATION_ERROR");
+  const kind = p.kind ?? "coin";
+  if (kind !== "coin" && kind !== "whole" && kind !== "coinless") {
+    throw new SphereError(
+      `unsupported intent kind '${String(kind)}' \u2014 not resumable by this client`,
+      "VALIDATION_ERROR"
+    );
   }
-  return p;
+  return kind === "coin" ? validateCoinPayload(p) : validateWholePayload(p);
 }
 
 // modules/payments-v2/convergence.ts
@@ -1578,46 +1646,314 @@ async function openRow(entry, journal, decryptPayload) {
   } catch {
     payload = null;
   }
-  const total = Array.isArray(payload?.direct) ? payload.direct.length + (payload.split !== void 0 ? 1 : 0) : 0;
-  const certified = distinctOpCount(journal);
-  return {
-    transferId: entry.transferId,
-    kind: "open",
-    recipient: typeof payload?.recipient === "string" ? payload.recipient : "",
-    coinId: typeof payload?.coinId === "string" ? payload.coinId : "",
-    amount: typeof payload?.amount === "string" ? payload.amount : "",
-    legs: { certified, total: Math.max(total, certified) },
-    deliveryPending: journal.length > 0,
-    createdAt: entry.createdAt
-  };
+  const total = Array.isArray(payload?.direct) ? payload.direct.length + (payload.split !== void 0 ? 1 : 0) : 0;
+  const certified = distinctOpCount(journal);
+  return {
+    transferId: entry.transferId,
+    kind: "open",
+    recipient: typeof payload?.recipient === "string" ? payload.recipient : "",
+    ...subject(payload),
+    legs: { certified, total: Math.max(total, certified) },
+    deliveryPending: journal.length > 0,
+    createdAt: entry.createdAt
+  };
+}
+function subject(payload) {
+  const rawKind = payload?.kind;
+  if (rawKind === "whole" || rawKind === "coinless") {
+    const tokenId = payload?.direct?.[0];
+    return { coinId: "", amount: "", ...typeof tokenId === "string" ? { tokenId } : {} };
+  }
+  const coin = payload;
+  return {
+    coinId: typeof coin?.coinId === "string" ? coin.coinId : "",
+    amount: typeof coin?.amount === "string" ? coin.amount : ""
+  };
+}
+function journalOnlyRow(transferId, entries) {
+  const certified = distinctOpCount(entries);
+  return {
+    transferId,
+    kind: "open",
+    recipient: entries[0].recipientPubkey,
+    coinId: "",
+    amount: "",
+    legs: { certified, total: certified },
+    deliveryPending: true,
+    createdAt: 0
+  };
+}
+function shortfallRow(entry) {
+  return {
+    transferId: entry.transferId,
+    kind: "shortfall",
+    recipient: entry.recipient,
+    coinId: entry.coinId,
+    amount: entry.remainingAmount,
+    legs: { certified: entry.committedTokenIds.length, total: entry.committedTokenIds.length },
+    deliveryPending: false,
+    createdAt: entry.createdAt
+  };
+}
+function distinctOpCount(entries) {
+  return new Set(entries.map((entry) => entry.opIndex)).size;
+}
+
+// modules/payments-v2/inventory/token-data.ts
+async function readTokenData(deps, tokenId) {
+  if (deps.view.stateHashOf(tokenId) === void 0) {
+    throw new SphereError(`Token ${tokenId} is not in inventory`, "VALIDATION_ERROR");
+  }
+  const bytes = (await deps.storagePort.getBlobs([tokenId])).get(tokenId);
+  if (bytes === void 0) {
+    throw new SphereError(`Token ${tokenId} has no blob in storage`, "STORAGE_ERROR");
+  }
+  return deps.engine.readTokenData(await deps.engine.decodeToken({ tokenId, token: bytes }));
+}
+
+// modules/payments-v2/machine/payload.ts
+function buildPayload(recipientPubkey, request, spend, spentStates) {
+  return {
+    v: 2,
+    kind: "coin",
+    recipient: recipientPubkey,
+    coinId: request.coinId,
+    amount: request.amount,
+    ...request.memo !== void 0 ? { memo: request.memo } : {},
+    direct: [...spend.plan.direct],
+    ...spend.plan.split !== void 0 ? {
+      split: {
+        tokenId: spend.plan.split.tokenId,
+        splitAmount: spend.plan.split.splitAmount.toString(),
+        remainderAmount: spend.plan.split.remainderAmount.toString()
+      }
+    } : {},
+    spentStates
+  };
+}
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function buildWholePayload(recipientPubkey, request, spentStates) {
+  return {
+    v: 2,
+    kind: "whole",
+    recipient: recipientPubkey,
+    ...request.memo !== void 0 ? { memo: request.memo } : {},
+    direct: [request.tokenId],
+    spentStates
+  };
+}
+
+// modules/payments-v2/mint-params.ts
+function mintParams(recipientPubkey, coinId, amount) {
+  return { recipientPubkey, value: { assets: [{ coinId, amount }] } };
+}
+
+// modules/payments-v2/mint.ts
+function runMintUnderJournal(deps, input) {
+  return mintUnderJournal(deps, input);
+}
+async function mintUnderJournal(deps, input) {
+  const { mintId, coinId, amount } = input;
+  const engine = deps.engine;
+  const entry = {
+    mintId,
+    coinId,
+    amount: amount.toString(),
+    tokenId: "",
+    createdAt: deps.now()
+  };
+  await deps.mintJournal.upsert(entry);
+  let token;
+  try {
+    token = await engine.mint(mintParams(deps.ownPubkeyBytes, coinId, amount), { transferId: mintId });
+  } catch (err) {
+    deps.armHeartbeat();
+    return { success: false, error: messageOf(err) };
+  }
+  if (token.blob.tokenId !== entry.tokenId) {
+    await deps.mintJournal.upsert({ ...entry, tokenId: token.blob.tokenId });
+  }
+  try {
+    await finalizeMint(deps, mintId, token, coinId, amount.toString());
+  } catch (err) {
+    deps.armHeartbeat();
+    return { success: false, tokenId: token.blob.tokenId, error: messageOf(err) };
+  }
+  return { success: true, tokenId: token.blob.tokenId };
+}
+async function finalizeMint(deps, mintId, token, coinId, amount) {
+  const engine = deps.engine;
+  const bytes = token.blob.token;
+  const digest = bytesToHex(sha256(bytes));
+  const keys = await deps.storagePort.uploadBlobs([{ sha256: digest, bytes }]);
+  const key = keys.get(digest);
+  if (key === void 0) {
+    throw new SphereError(`no upload key returned for mint blob ${digest}`, "STORAGE_ERROR");
+  }
+  await deps.storagePort.applyDelta({
+    transferId: mintId,
+    spent: [],
+    added: [{ tokenId: token.blob.tokenId, key }]
+  });
+  await deps.recordMint({
+    tokenId: token.blob.tokenId,
+    assets: [{ coinId, amount }]
+  });
+  await deps.mintJournal.removeByKey(mintId);
+  deps.noteHeldState(token.blob.tokenId, (await engine.deliveryKeys(bytes)).stateHash);
+  deps.refreshView();
+}
+
+// modules/payments-v2/inventory/presentation.ts
+function toToken(tokenId, snapshot, asset, registry, flags) {
+  const iconUrl = registry.getIconUrl(asset.coinId);
+  return {
+    id: tokenId,
+    coinId: asset.coinId,
+    symbol: registry.getSymbol(asset.coinId),
+    name: registry.getName(asset.coinId),
+    decimals: registry.getDecimals(asset.coinId),
+    ...iconUrl !== null ? { iconUrl } : {},
+    amount: asset.amount,
+    status: flags.transferring ? "transferring" : "confirmed",
+    createdAt: snapshot.createdAt,
+    updatedAt: snapshot.updatedAt,
+    lazy: true,
+    ...flags.suspectedSpent ? { suspectedSpent: true } : {}
+  };
+}
+function aggregateAssets(entries, isTransferring, registry) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const [tokenId, entry] of entries) {
+    const moving = isTransferring(tokenId);
+    for (const asset of entry.assets) {
+      let group = groups.get(asset.coinId);
+      if (!group) {
+        group = { total: 0n, count: 0, transferring: 0n, transferringCount: 0 };
+        groups.set(asset.coinId, group);
+      }
+      if (moving) {
+        group.transferring += BigInt(asset.amount);
+        group.transferringCount += 1;
+      } else {
+        group.total += BigInt(asset.amount);
+        group.count += 1;
+      }
+    }
+  }
+  return [...groups].map(([coinId, totals]) => toAsset(coinId, totals, registry));
+}
+function toAsset(coinId, totals, registry) {
+  const iconUrl = registry.getIconUrl(coinId);
+  return {
+    coinId,
+    symbol: registry.getSymbol(coinId),
+    name: registry.getName(coinId),
+    decimals: registry.getDecimals(coinId),
+    ...iconUrl !== null ? { iconUrl } : {},
+    totalAmount: totals.total.toString(),
+    tokenCount: totals.count,
+    confirmedAmount: totals.total.toString(),
+    unconfirmedAmount: "0",
+    confirmedTokenCount: totals.count,
+    unconfirmedTokenCount: 0,
+    transferringTokenCount: totals.transferringCount,
+    transferringAmount: totals.transferring.toString(),
+    priceUsd: null,
+    priceEur: null,
+    change24h: null,
+    fiatValueUsd: null,
+    fiatValueEur: null
+  };
+}
+function priceIdOf(registry, coinId) {
+  return registry.getName(coinId).toLowerCase();
+}
+async function withPrices(raw, registry, price) {
+  try {
+    const ids = [...new Set(raw.map((a) => priceIdOf(registry, a.coinId)))];
+    const quotes = await price.getPrices(ids);
+    return raw.map((a) => priceOne(a, quotes.get(priceIdOf(registry, a.coinId))));
+  } catch {
+    return raw;
+  }
 }
-function journalOnlyRow(transferId, entries) {
-  const certified = distinctOpCount(entries);
+function priceOne(asset, quote) {
+  if (!quote) return asset;
+  const human = Number(asset.totalAmount) / Math.pow(10, asset.decimals);
   return {
-    transferId,
-    kind: "open",
-    recipient: entries[0].recipientPubkey,
-    coinId: "",
-    amount: "",
-    legs: { certified, total: certified },
-    deliveryPending: true,
-    createdAt: 0
+    ...asset,
+    priceUsd: quote.priceUsd,
+    priceEur: quote.priceEur ?? null,
+    change24h: quote.change24h ?? null,
+    fiatValueUsd: human * quote.priceUsd,
+    fiatValueEur: quote.priceEur != null ? human * quote.priceEur : null
   };
 }
-function shortfallRow(entry) {
-  return {
-    transferId: entry.transferId,
-    kind: "shortfall",
-    recipient: entry.recipient,
-    coinId: entry.coinId,
-    amount: entry.remainingAmount,
-    legs: { certified: entry.committedTokenIds.length, total: entry.committedTokenIds.length },
-    deliveryPending: false,
-    createdAt: entry.createdAt
+function transferringToken(tokenId, coinId, amount, registry, now) {
+  const snapshot = { assets: [], createdAt: now, updatedAt: now };
+  return toToken(tokenId, snapshot, { coinId, amount: amount.toString() }, registry, {
+    transferring: true,
+    suspectedSpent: false
+  });
+}
+
+// modules/payments-v2/send-whole.ts
+async function materializeWholeSpend(deps, input) {
+  const { engine } = deps;
+  const tokenId = input.request.tokenId;
+  const bytes = (await deps.storagePort.getBlobs([tokenId])).get(tokenId);
+  if (bytes === void 0) {
+    throw new SphereError(`Selected source ${tokenId} has no blob in storage`, "STORAGE_ERROR");
+  }
+  const token = await engine.decodeToken({ tokenId, token: bytes });
+  if (token.valueEnvelope === "bare_collection") {
+    throw new SphereError(
+      `Token ${tokenId} carries a value envelope this SDK cannot read, so its coins cannot be accounted for; it cannot be sent`,
+      "VALIDATION_ERROR"
+    );
+  }
+  if (input.requireCoinless && token.value !== null) {
+    throw new SphereError(
+      `Token ${tokenId} carries coin value and cannot be sent with sendCoinless \u2014 use sendWholeToken, which requires coin-transfer authority`,
+      "VALIDATION_ERROR"
+    );
+  }
+  const keys = await engine.deliveryKeys(bytes);
+  const payload = buildWholePayload(input.recipientPubkey, input.request, {
+    [tokenId]: { local: keys.stateHash, protocol: keys.stateHash }
+  });
+  const plan = {
+    transferId: input.transferId,
+    recipientPubkey: input.recipientPubkey,
+    payload,
+    ops: buildOps(payload),
+    sources: /* @__PURE__ */ new Map([[tokenId, token]]),
+    ...input.request.memo !== void 0 ? { memo: input.request.memo } : {}
   };
+  const sourceTokens = (token.value?.assets ?? []).map(
+    (asset) => transferringToken(tokenId, asset.coinId, asset.amount, deps.registry, deps.now)
+  );
+  return { transferId: input.transferId, coinId: "", plan, sourceIds: input.sourceIds, sourceTokens };
 }
-function distinctOpCount(entries) {
-  return new Set(entries.map((entry) => entry.opIndex)).size;
+
+// modules/payments-v2/send-errors.ts
+function partialize(err, run) {
+  if (run.delivered.length === 0) return err;
+  return new PartialSendConflictError(
+    "Part of your payment was sent; the remaining amount could not be completed (see cause). The delivered portion is final \u2014 re-plan only the shortfall, never the full amount.",
+    run.firstPartialId ?? "",
+    [...run.delivered],
+    run.amount,
+    err
+  );
+}
+function stampTransferId(err, transferId) {
+  if (err instanceof SphereError && isPossiblyCommittedSendOutcome(err) && err.transferId === void 0) {
+    err.transferId = transferId;
+  }
 }
 
 // modules/payments-v2/recipient.ts
@@ -1668,11 +2004,6 @@ async function splitOpIndex(deps, envelope) {
   return Array.isArray(payload.direct) ? payload.direct.length : 0;
 }
 
-// modules/payments-v2/mint-params.ts
-function mintParams(recipientPubkey, coinId, amount) {
-  return { recipientPubkey, value: { assets: [{ coinId, amount }] } };
-}
-
 // modules/payments-v2/prewarm-cache.ts
 var PrewarmCache = class _PrewarmCache {
   entries = /* @__PURE__ */ new Map();
@@ -1752,123 +2083,6 @@ async function takeSourceBlobs(deps, sourceIds) {
   return blobs;
 }
 
-// modules/payments-v2/inventory/presentation.ts
-function toToken(tokenId, snapshot, asset, registry, flags) {
-  const iconUrl = registry.getIconUrl(asset.coinId);
-  return {
-    id: tokenId,
-    coinId: asset.coinId,
-    symbol: registry.getSymbol(asset.coinId),
-    name: registry.getName(asset.coinId),
-    decimals: registry.getDecimals(asset.coinId),
-    ...iconUrl !== null ? { iconUrl } : {},
-    amount: asset.amount,
-    status: flags.transferring ? "transferring" : "confirmed",
-    createdAt: snapshot.createdAt,
-    updatedAt: snapshot.updatedAt,
-    lazy: true,
-    ...flags.suspectedSpent ? { suspectedSpent: true } : {}
-  };
-}
-function aggregateAssets(entries, isTransferring, registry) {
-  const groups = /* @__PURE__ */ new Map();
-  for (const [tokenId, entry] of entries) {
-    const moving = isTransferring(tokenId);
-    for (const asset of entry.assets) {
-      let group = groups.get(asset.coinId);
-      if (!group) {
-        group = { total: 0n, count: 0, transferring: 0n, transferringCount: 0 };
-        groups.set(asset.coinId, group);
-      }
-      if (moving) {
-        group.transferring += BigInt(asset.amount);
-        group.transferringCount += 1;
-      } else {
-        group.total += BigInt(asset.amount);
-        group.count += 1;
-      }
-    }
-  }
-  return [...groups].map(([coinId, totals]) => toAsset(coinId, totals, registry));
-}
-function toAsset(coinId, totals, registry) {
-  const iconUrl = registry.getIconUrl(coinId);
-  return {
-    coinId,
-    symbol: registry.getSymbol(coinId),
-    name: registry.getName(coinId),
-    decimals: registry.getDecimals(coinId),
-    ...iconUrl !== null ? { iconUrl } : {},
-    totalAmount: totals.total.toString(),
-    tokenCount: totals.count,
-    confirmedAmount: totals.total.toString(),
-    unconfirmedAmount: "0",
-    confirmedTokenCount: totals.count,
-    unconfirmedTokenCount: 0,
-    transferringTokenCount: totals.transferringCount,
-    transferringAmount: totals.transferring.toString(),
-    priceUsd: null,
-    priceEur: null,
-    change24h: null,
-    fiatValueUsd: null,
-    fiatValueEur: null
-  };
-}
-function priceIdOf(registry, coinId) {
-  return registry.getName(coinId).toLowerCase();
-}
-async function withPrices(raw, registry, price) {
-  try {
-    const ids = [...new Set(raw.map((a) => priceIdOf(registry, a.coinId)))];
-    const quotes = await price.getPrices(ids);
-    return raw.map((a) => priceOne(a, quotes.get(priceIdOf(registry, a.coinId))));
-  } catch {
-    return raw;
-  }
-}
-function priceOne(asset, quote) {
-  if (!quote) return asset;
-  const human = Number(asset.totalAmount) / Math.pow(10, asset.decimals);
-  return {
-    ...asset,
-    priceUsd: quote.priceUsd,
-    priceEur: quote.priceEur ?? null,
-    change24h: quote.change24h ?? null,
-    fiatValueUsd: human * quote.priceUsd,
-    fiatValueEur: quote.priceEur != null ? human * quote.priceEur : null
-  };
-}
-function transferringToken(tokenId, coinId, amount, registry, now) {
-  const snapshot = { assets: [], createdAt: now, updatedAt: now };
-  return toToken(tokenId, snapshot, { coinId, amount: amount.toString() }, registry, {
-    transferring: true,
-    suspectedSpent: false
-  });
-}
-
-// modules/payments-v2/machine/payload.ts
-function buildPayload(recipientPubkey, request, spend, spentStates) {
-  return {
-    v: 2,
-    recipient: recipientPubkey,
-    coinId: request.coinId,
-    amount: request.amount,
-    ...request.memo !== void 0 ? { memo: request.memo } : {},
-    direct: [...spend.plan.direct],
-    ...spend.plan.split !== void 0 ? {
-      split: {
-        tokenId: spend.plan.split.tokenId,
-        splitAmount: spend.plan.split.splitAmount.toString(),
-        remainderAmount: spend.plan.split.remainderAmount.toString()
-      }
-    } : {},
-    spentStates
-  };
-}
-function messageOf(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-
 // node_modules/@noble/ciphers/utils.js
 function isBytes2(a) {
   return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array" && "BYTES_PER_ELEMENT" in a && a.BYTES_PER_ELEMENT === 1;
@@ -2720,6 +2934,14 @@ function decryptField(key, envelope) {
 }
 
 // modules/payments-v2/history/History.ts
+function wireAssets(assets) {
+  return assets.map((a) => ({ coinId: a.coinId, amount: a.amount }));
+}
+function isPermanentReject(err) {
+  const status = err?.status;
+  if (typeof status !== "number") return false;
+  return status >= 400 && status < 500 && status !== 408 && status !== 429;
+}
 var WIRE_TOKEN_ID = /^(?:[0-9a-f]{2}){1,64}$/;
 var WIRE_PUBKEY = /^0[23][0-9a-f]{64}$/;
 var History = class {
@@ -2744,7 +2966,7 @@ var History = class {
       dedupKey: input.transferId,
       id: (this.deps.newId ?? randomUUID)(),
       type: "SENT",
-      assets: [{ coinId: input.coinId, amount: input.amount }],
+      assets: wireAssets(input.assets),
       ts: this.ts(input.timestamp),
       transferId: input.transferId,
       ...this.wireTokenId(input.tokenId),
@@ -2757,7 +2979,7 @@ var History = class {
       dedupKey: `RECEIVED:${input.tokenId.toLowerCase()}:${input.stateHash.toLowerCase()}`,
       id: (this.deps.newId ?? randomUUID)(),
       type: "RECEIVED",
-      assets: [{ coinId: input.coinId, amount: input.amount }],
+      assets: wireAssets(input.assets),
       ts: this.ts(input.timestamp),
       ...input.transferId !== void 0 ? { transferId: input.transferId } : {},
       ...this.wireTokenId(input.tokenId),
@@ -2770,7 +2992,7 @@ var History = class {
       dedupKey: `MINT:${input.tokenId.toLowerCase()}`,
       id: (this.deps.newId ?? randomUUID)(),
       type: "MINT",
-      assets: [{ coinId: input.coinId, amount: input.amount }],
+      assets: wireAssets(input.assets),
       ts: this.ts(input.timestamp),
       ...this.wireTokenId(input.tokenId)
     }));
@@ -2781,7 +3003,10 @@ var History = class {
     try {
       await this.deps.client.postHistory([record]);
     } catch (err) {
-      this.deps.log?.("history POST failed (dedupKey makes retry safe)", err);
+      this.deps.log?.(
+        isPermanentReject(err) ? "history POST REJECTED \u2014 the record shape is refused; no retry can fix it" : "history POST failed (dedupKey makes retry safe)",
+        err
+      );
       return;
     }
     this.deps.emit("history:updated", this.toEntry(record));
@@ -2848,6 +3073,13 @@ var CURSOR_KEY = STORE_KEYS.streamCursor("inventory");
 function stateKey(tokenId, stateHash) {
   return `${tokenId}:${stateHash}`;
 }
+function unchanged(prev, item, tokenType) {
+  return prev.seq === item.seq && prev.status === item.status && prev.stateHash === item.stateHash && tokenType === prev.tokenType;
+}
+function isCoinless(item, prev) {
+  if (item.status !== "active") return prev?.coinless ?? false;
+  return (item.assets?.length ?? 0) === 0;
+}
 var InventoryView = class {
   constructor(deps) {
     this.deps = deps;
@@ -2941,14 +3173,26 @@ var InventoryView = class {
   pool(coinId) {
     const out = [];
     for (const [tokenId, entry] of this.mirror) {
-      if (entry.status !== "active") continue;
-      if (this.inFlight.has(tokenId) && !this.pinned(tokenId)) continue;
-      if (this.suspected.has(stateKey(tokenId, entry.stateHash))) continue;
+      if (!this.isSpendable(tokenId, entry)) continue;
       const asset = entry.assets.find((a) => a.coinId === coinId);
       if (asset) out.push({ tokenId, amount: BigInt(asset.amount) });
     }
     return out;
   }
+  /**
+   * The eligibility gates every spend shares, coin or token — ONE definition, so a
+   * single probe covers both verbs and neither can drift from the other.
+   */
+  isSpendable(tokenId, entry) {
+    if (entry.status !== "active") return false;
+    if (this.inFlight.has(tokenId) && !this.pinned(tokenId)) return false;
+    return !this.suspected.has(stateKey(tokenId, entry.stateHash));
+  }
+  /** Is this NAMED token spendable whole — coinless or valued (#777)? */
+  spendableToken(tokenId) {
+    const entry = this.mirror.get(tokenId);
+    return entry !== void 0 && this.isSpendable(tokenId, entry);
+  }
   /**
    * Current mirrored state of an ACTIVE token, or undefined when it is unknown
    * or tombstoned. Exists so a cached blob can be state-scoped (F6): a blob is
@@ -2974,6 +3218,29 @@ var InventoryView = class {
     }
     return out;
   }
+  /**
+   * Coinless holdings (#777) — DISJOINT from tokens(): an entry is coinless
+   * exactly when it is not, so no mirror row can appear in both reads.
+   */
+  coinless(registry) {
+    const out = [];
+    for (const [tokenId, entry] of this.mirror) {
+      if (entry.status !== "active" || !entry.coinless) continue;
+      const meta = entry.tokenType !== void 0 ? registry.getTypeMeta?.(entry.tokenType) : null;
+      out.push({
+        tokenId,
+        ...entry.tokenType !== void 0 ? { tokenType: entry.tokenType } : {},
+        ...meta ? { name: meta.name } : {},
+        ...meta?.iconUrl != null ? { iconUrl: meta.iconUrl } : {},
+        stateHash: entry.stateHash,
+        transferring: this.held(tokenId),
+        ...this.suspected.has(stateKey(tokenId, entry.stateHash)) ? { suspectedSpent: true } : {},
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt
+      });
+    }
+    return out;
+  }
   async assets(registry, price) {
     const raw = aggregateAssets(this.activeEntries(), (tokenId) => this.held(tokenId), registry);
     if (!price || raw.length === 0) return raw;
@@ -3045,14 +3312,19 @@ var InventoryView = class {
   applyOne(item, now) {
     const prev = this.mirror.get(item.tokenId);
     if (prev && item.seq < prev.seq) return false;
-    if (prev && prev.seq === item.seq && prev.status === item.status && prev.stateHash === item.stateHash) {
-      return false;
-    }
+    const tokenType = item.tokenType ?? prev?.tokenType;
+    if (prev && unchanged(prev, item, tokenType)) return false;
     this.mirror.set(item.tokenId, {
       stateHash: item.stateHash,
       seq: item.seq,
       status: item.status,
-      assets: item.assets ?? prev?.assets ?? [],
+      // ONLY a tombstone inherits: it omits assets for an unrelated reason and
+      // recoverRemoved must know the amount it restores. An ACTIVE row that omits
+      // them is stating coinlessness, and inheriting there would keep stale assets
+      // in tokens() while `coinless` is true — the row in BOTH reads (§16).
+      assets: item.assets ?? (item.status === "removed" ? prev?.assets ?? [] : []),
+      coinless: isCoinless(item, prev),
+      ...tokenType !== void 0 ? { tokenType } : {},
       createdAt: prev?.createdAt ?? now,
       updatedAt: now
     });
@@ -3143,6 +3415,73 @@ var InventoryView = class {
   }
 };
 
+// token-engine/sdk.ts
+import { StateTransitionClient } from "@unicitylabs/state-transition-sdk/lib/StateTransitionClient.js";
+import { AggregatorClient } from "@unicitylabs/state-transition-sdk/lib/api/AggregatorClient.js";
+import { NetworkId } from "@unicitylabs/state-transition-sdk/lib/api/NetworkId.js";
+import { CertificationData } from "@unicitylabs/state-transition-sdk/lib/api/CertificationData.js";
+import { CertificationResponse, CertificationStatus } from "@unicitylabs/state-transition-sdk/lib/api/CertificationResponse.js";
+import { StateId } from "@unicitylabs/state-transition-sdk/lib/api/StateId.js";
+import { InclusionProof } from "@unicitylabs/state-transition-sdk/lib/api/InclusionProof.js";
+import { InclusionProofResponse } from "@unicitylabs/state-transition-sdk/lib/api/InclusionProofResponse.js";
+import { JsonRpcNetworkError } from "@unicitylabs/state-transition-sdk/lib/api/json-rpc/JsonRpcNetworkError.js";
+import { RootTrustBase } from "@unicitylabs/state-transition-sdk/lib/api/bft/RootTrustBase.js";
+import { waitInclusionProof } from "@unicitylabs/state-transition-sdk/lib/util/InclusionProofUtils.js";
+import { InclusionProofVerificationStatus } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/rule/InclusionProofVerificationRule.js";
+import { Token } from "@unicitylabs/state-transition-sdk/lib/transaction/Token.js";
+import { MintTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/MintTransaction.js";
+import { TransferTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/TransferTransaction.js";
+import { CertifiedMintTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/CertifiedMintTransaction.js";
+import { CertifiedTransferTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/CertifiedTransferTransaction.js";
+import { TokenId } from "@unicitylabs/state-transition-sdk/lib/transaction/TokenId.js";
+import { TokenType } from "@unicitylabs/state-transition-sdk/lib/transaction/TokenType.js";
+import { TokenSalt } from "@unicitylabs/state-transition-sdk/lib/transaction/TokenSalt.js";
+import { StateMask } from "@unicitylabs/state-transition-sdk/lib/transaction/StateMask.js";
+import { MintJustificationVerifierService } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/MintJustificationVerifierService.js";
+import { TokenIssuanceVerifierService } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/TokenIssuanceVerifierService.js";
+import { VerificationContext } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/VerificationContext.js";
+import { UnicityCertificateVerifier } from "@unicitylabs/state-transition-sdk/lib/api/bft/verification/UnicityCertificateVerifier.js";
+import { UnicitySealQuorumSignaturesVerificationRule } from "@unicitylabs/state-transition-sdk/lib/api/bft/verification/rule/UnicitySealQuorumSignaturesVerificationRule.js";
+import { VerifiedSealCache } from "@unicitylabs/state-transition-sdk/lib/api/bft/verification/VerifiedSealCache.js";
+import { Secp256k1SignatureVerifier } from "@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/Secp256k1SignatureVerifier.js";
+import { WorkerTokenVerifier } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/worker/WorkerTokenVerifier.js";
+import { EncodedPredicate } from "@unicitylabs/state-transition-sdk/lib/predicate/EncodedPredicate.js";
+import { SignaturePredicate } from "@unicitylabs/state-transition-sdk/lib/predicate/builtin/SignaturePredicate.js";
+import { SignaturePredicateUnlockScript } from "@unicitylabs/state-transition-sdk/lib/predicate/builtin/SignaturePredicateUnlockScript.js";
+import { BurnPredicate } from "@unicitylabs/state-transition-sdk/lib/predicate/builtin/BurnPredicate.js";
+import { PredicateVerifierService } from "@unicitylabs/state-transition-sdk/lib/predicate/verification/PredicateVerifierService.js";
+import { SigningService } from "@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/SigningService.js";
+import { Signature } from "@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/Signature.js";
+import { MintSigningService } from "@unicitylabs/state-transition-sdk/lib/crypto/MintSigningService.js";
+import { HashAlgorithm } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/HashAlgorithm.js";
+import { DataHash } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHash.js";
+import { DataHasher } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHasher.js";
+import { DataHasherFactory } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHasherFactory.js";
+import { CborSerializer } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborSerializer.js";
+import { CborDeserializer } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborDeserializer.js";
+import { CborError } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborError.js";
+import { CborReader } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborReader.js";
+import { MajorType } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/MajorType.js";
+import { Asset } from "@unicitylabs/state-transition-sdk/lib/payment/asset/Asset.js";
+import { AssetId } from "@unicitylabs/state-transition-sdk/lib/payment/asset/AssetId.js";
+import { PaymentAssetCollection } from "@unicitylabs/state-transition-sdk/lib/payment/asset/PaymentAssetCollection.js";
+import { TokenSplit } from "@unicitylabs/state-transition-sdk/lib/payment/TokenSplit.js";
+import { SplitTokenRequest } from "@unicitylabs/state-transition-sdk/lib/payment/SplitTokenRequest.js";
+import { SplitToken } from "@unicitylabs/state-transition-sdk/lib/payment/SplitToken.js";
+import { SplitAllocationProof } from "@unicitylabs/state-transition-sdk/lib/payment/SplitAllocationProof.js";
+import { SplitMintJustification } from "@unicitylabs/state-transition-sdk/lib/payment/SplitMintJustification.js";
+import { SplitMintJustificationVerifier } from "@unicitylabs/state-transition-sdk/lib/payment/SplitMintJustificationVerifier.js";
+import { VerificationStatus } from "@unicitylabs/state-transition-sdk/lib/verification/VerificationStatus.js";
+import { VerificationResult } from "@unicitylabs/state-transition-sdk/lib/verification/VerificationResult.js";
+import { HexConverter } from "@unicitylabs/state-transition-sdk/lib/util/HexConverter.js";
+import { BigintConverter } from "@unicitylabs/state-transition-sdk/lib/util/BigintConverter.js";
+import { BitString } from "@unicitylabs/state-transition-sdk/lib/util/BitString.js";
+
+// token-engine/value-envelope.ts
+function isCoinlessEnvelope(envelope) {
+  return envelope.startsWith("none_");
+}
+
 // modules/payments-v2/receive/Receive.ts
 var ACK_BATCH_SIZE = 200;
 var REFRESH_INTERVAL_MS = 2500;
@@ -3283,7 +3622,12 @@ async function screen(deps, engine, entry) {
   }
   return {
     kind: "accept",
-    record: { tokenId: keys.tokenId, stateHash: keys.stateHash, assets: toAssetAmounts(token) }
+    record: {
+      tokenId: keys.tokenId,
+      stateHash: keys.stateHash,
+      assets: toAssetAmounts(token),
+      ...isCoinlessEnvelope(token.valueEnvelope) ? { tokenType: token.tokenType } : {}
+    }
   };
 }
 async function announce(deps, entry, record) {
@@ -3294,6 +3638,7 @@ async function announce(deps, entry, record) {
       tokenId: record.tokenId,
       stateHash: record.stateHash,
       assets: record.assets,
+      ...record.tokenType !== void 0 ? { tokenType: record.tokenType } : {},
       ...entry.senderPubkey !== void 0 ? { senderPubkey: entry.senderPubkey } : {},
       ...entry.senderNametag !== void 0 ? { senderNametag: entry.senderNametag } : {},
       ...entry.memo !== void 0 ? { memo: entry.memo } : {},
@@ -3307,6 +3652,19 @@ async function announce(deps, entry, record) {
     senderPubkey: entry.senderPubkey ?? "",
     ...entry.senderNametag !== void 0 ? { senderNametag: entry.senderNametag } : {},
     tokens: record.assets.map((asset) => toUiToken(record.tokenId, asset, deps.registry, receivedAt)),
+    // #777: named here rather than mapped from assets, which announced an EMPTY list.
+    ...record.tokenType !== void 0 ? {
+      coinless: [
+        {
+          tokenId: record.tokenId,
+          tokenType: record.tokenType,
+          stateHash: record.stateHash,
+          transferring: false,
+          createdAt: receivedAt,
+          updatedAt: receivedAt
+        }
+      ]
+    } : {},
     ...entry.memo !== void 0 ? { memo: entry.memo } : {},
     receivedAt
   };
@@ -3972,6 +4330,34 @@ var SpendQueue = class {
     }
     return { kind: "queued", settled: this.enqueue(reservationId, request.coinId, amount) };
   }
+  /**
+   * #777: reserve a NAMED coinless source. Never queues — there is nothing to wait
+   * for. A coin plan waits because some OTHER combination may free up; a named
+   * token is either free now or held by a reservation that only its own transfer
+   * can release, so queueing would block until a timeout on a spend that cannot
+   * become possible.
+   */
+  planWhole(reservationId, tokenId) {
+    if (this.destroyed) {
+      throw new SphereError("Module has been destroyed", "MODULE_DESTROYED");
+    }
+    const unproven = this.deps.ledger.unprovenReason();
+    if (unproven !== null) {
+      throw new SphereError(`Cannot spend yet: ${unproven}`, "SEND_SYNC_PENDING");
+    }
+    if (this.deps.spendableToken?.(tokenId) !== true) {
+      throw new SphereError(`Token ${tokenId} is not a spendable holding`, "VALIDATION_ERROR");
+    }
+    const holder = this.deps.ledger.holderOf(tokenId);
+    if (holder !== void 0) {
+      throw new SphereError(
+        `Token ${tokenId} is already reserved by transfer ${holder}`,
+        "VALIDATION_ERROR"
+      );
+    }
+    this.deps.ledger.reserve(reservationId, [{ tokenId }]);
+    return { reservationId, plan: { direct: [tokenId] } };
+  }
   /**
    * The sources `plan()` WOULD pick right now, reserving nothing and queueing
    * nothing — a read-only probe used to warm blobs while the user is still
@@ -4161,6 +4547,7 @@ function composeFacadeParts(deps, hooks) {
   const queue = new SpendQueue({
     ledger,
     getPool: (coinId) => view.pool(coinId),
+    spendableToken: (tokenId) => view.spendableToken(tokenId),
     ...deps.workBudget !== void 0 ? { workBudget: deps.workBudget } : {}
   });
   const historyStore = new History({
@@ -4241,13 +4628,12 @@ function buildMachineDeps(deps, hooks, historyStore) {
     ...deps.ownNametag !== void 0 ? { ownNametag: deps.ownNametag } : {},
     emit: deps.emit,
     now: deps.now ?? Date.now,
-    recordHistory: async ({ transferId, payload, committedAmount }) => {
+    recordHistory: async ({ transferId, payload, committedAmount, committedAssets }) => {
       await historyStore.recordSent({
         transferId,
-        coinId: payload.coinId,
-        // §5.9: the SETTLED amount (machine-computed from the certified
-        // recipient blobs), never payload.amount — the plan.
-        amount: committedAmount,
+        // §5.9: the SETTLED amount, never payload.amount — the plan. A token
+        // spend moved no coin: `assets: []` + tokenId (wallet-api#151 / §10).
+        ...isWholeIntent(payload) ? { assets: committedAssets ?? [], tokenId: payload.direct[0] } : { assets: [{ coinId: payload.coinId, amount: committedAmount }] },
         recipientPubkey: payload.recipient,
         ...payload.memo !== void 0 ? { memo: payload.memo } : {}
       });
@@ -4282,12 +4668,10 @@ function buildReceive(deps, hooks, historyStore, heldStates, refreshView) {
   });
 }
 async function recordReceived(historyStore, record) {
-  const first = record.assets[0];
   await historyStore.recordReceived({
     tokenId: record.tokenId,
     stateHash: record.stateHash,
-    coinId: first?.coinId ?? "",
-    amount: first?.amount ?? "0",
+    assets: record.assets,
     ...record.senderPubkey !== void 0 ? { senderPubkey: record.senderPubkey } : {},
     ...record.senderNametag !== void 0 ? { senderNametag: record.senderNametag } : {},
     ...record.memo !== void 0 ? { memo: record.memo } : {},
@@ -4435,6 +4819,13 @@ var PaymentsFacade = class {
   tokens(filter) {
     return this.view.tokens(this.deps.registry, filter);
   }
+  coinless() {
+    return this.view.coinless(this.deps.registry);
+  }
+  tokenData(tokenId) {
+    const deps = { engine: this.engine(), view: this.view, storagePort: this.deps.storagePort };
+    return readTokenData(deps, tokenId);
+  }
   history(page) {
     return this.historyStore.page(page ?? {});
   }
@@ -4457,7 +4848,14 @@ var PaymentsFacade = class {
     return { queue: this.queue, view: this.view, storagePort: this.deps.storagePort, cache: this.prewarmed };
   }
   send(request) {
-    return this.track(this.sendOutcome(request));
+    return this.track(this.runJob({ kind: "coin", request }, request.amount));
+  }
+  sendWholeToken(request) {
+    return this.track(this.runJob({ kind: "whole", request, requireCoinless: false }, "0"));
+  }
+  /** NFT-scoped twin: refuses a valued source. */
+  sendCoinless(request) {
+    return this.track(this.runJob({ kind: "whole", request, requireCoinless: true }, "0"));
   }
   async receive() {
     const transfers = await this.track(this.receiveLoop.drainOnce());
@@ -4489,12 +4887,25 @@ var PaymentsFacade = class {
   nowMs() {
     return (this.deps.now ?? Date.now)();
   }
+  mintDeps() {
+    return {
+      engine: this.engine(),
+      mintJournal: this.machineStores.mintJournal,
+      storagePort: this.deps.storagePort,
+      recordMint: (input) => this.historyStore.recordMint(input),
+      armHeartbeat: () => this.heartbeat.arm(),
+      noteHeldState: (tokenId, stateHash) => void this.heldStates.set(tokenId, stateHash),
+      refreshView: () => this.trackTail(this.view.delta()),
+      ownPubkeyBytes: this.ownPubkeyBytes,
+      now: () => this.nowMs()
+    };
+  }
   // ── send policy (§5.5 + old-loop parity; the machine stays policy-free) ────
   /** The ONE place a send() outcome is shaped: success emits in finishSend, a
    *  CLEAN rejection emits `transfer:updated{status:'failed'}` here (§4). */
-  async sendOutcome(request) {
+  async runJob(job, amount) {
     const run = {
-      amount: request.amount,
+      amount,
       delivered: [],
       sentTokens: [],
       tokenTransfers: [],
@@ -4504,7 +4915,7 @@ var PaymentsFacade = class {
       lastTransferId: ""
     };
     try {
-      return await this.sendWithPolicy(request, run);
+      return await this.sendWithPolicy(job, run);
     } catch (err) {
       this.emitCleanFailure(err, run.lastTransferId);
       throw err;
@@ -4524,19 +4935,19 @@ var PaymentsFacade = class {
     };
     this.deps.emit("transfer:updated", failed);
   }
-  async sendWithPolicy(request, run) {
-    const recipient = await requireSameNetworkRecipient(this.deps, request.recipient);
+  async sendWithPolicy(job, run) {
+    const recipient = await requireSameNetworkRecipient(this.deps, job.request.recipient);
     for (let attempt = 0; ; attempt++) {
       let ctx;
       try {
-        ctx = await this.planAndMaterialize(recipient.chainPubkey, { ...request, amount: run.amount }, run);
+        ctx = await this.planAndMaterialize(recipient.chainPubkey, job, run);
       } catch (err) {
-        throw this.partialize(err, run);
+        throw partialize(err, run);
       }
       const disposition = await this.runAttempt(ctx);
-      if (disposition.kind === "rethrow") throw this.partialize(disposition.error, run);
+      if (disposition.kind === "rethrow") throw partialize(disposition.error, run);
       if (disposition.kind === "retry-full") {
-        if (attempt >= MAX_RESELECT) throw this.partialize(disposition.error, run);
+        if (job.kind === "whole" || attempt >= MAX_RESELECT) throw partialize(disposition.error, run);
         continue;
       }
       if (disposition.kind === "success") {
@@ -4592,7 +5003,7 @@ var PaymentsFacade = class {
   async disposeFailedAttempt(ctx, err) {
     if (isPossiblyCommittedSendOutcome(err)) {
       this.settleKeepOpen(ctx);
-      this.stampTransferId(err, ctx.transferId);
+      stampTransferId(err, ctx.transferId);
       return { kind: "rethrow", error: err };
     }
     const backstop = await this.machineStores.backstop.getByKey(ctx.transferId);
@@ -4626,7 +5037,7 @@ var PaymentsFacade = class {
   async disposeConvergeFailure(ctx, err) {
     if (isPossiblyCommittedSendOutcome(err)) {
       this.settleKeepOpen(ctx);
-      this.stampTransferId(err, ctx.transferId);
+      stampTransferId(err, ctx.transferId);
       return { kind: "rethrow", error: err };
     }
     if (classifyError(err) === "conflict") {
@@ -4637,9 +5048,29 @@ var PaymentsFacade = class {
     }
     return { kind: "rethrow", error: err };
   }
-  async planAndMaterialize(recipientPubkey, request, run) {
+  async planAndMaterialize(recipientPubkey, job, run) {
     const transferId = this.newId();
     run.lastTransferId = transferId;
+    if (job.kind === "whole") {
+      const spend2 = this.queue.planWhole(transferId, job.request.tokenId);
+      const sourceIds2 = this.markPlanned(transferId, "", spend2);
+      try {
+        return await materializeWholeSpend(
+          { engine: this.engine(), storagePort: this.deps.storagePort, registry: this.deps.registry, now: this.nowMs() },
+          {
+            transferId,
+            recipientPubkey,
+            request: job.request,
+            sourceIds: sourceIds2,
+            requireCoinless: job.requireCoinless
+          }
+        );
+      } catch (err) {
+        this.settleFailure(transferId, "", sourceIds2);
+        throw err;
+      }
+    }
+    const request = { ...job.request, amount: run.amount };
     const planned = this.queue.plan(transferId, { coinId: request.coinId, amount: request.amount });
     const spend = planned.kind === "planned" ? planned.spend : await planned.settled;
     const sourceIds = this.markPlanned(transferId, request.coinId, spend);
@@ -4773,22 +5204,6 @@ var PaymentsFacade = class {
     return result;
   }
   /** Nothing delivered → UNWRAPPED; after ≥1 delivered leg every failure surfaces as PartialSendConflictError over the settled set. */
-  partialize(err, run) {
-    if (run.delivered.length === 0) return err;
-    return new PartialSendConflictError(
-      "Part of your payment was sent; the remaining amount could not be completed (see cause). The delivered portion is final \u2014 re-plan only the shortfall, never the full amount.",
-      run.firstPartialId ?? "",
-      run.delivered,
-      run.amount,
-      err
-    );
-  }
-  /** #441: possibly-committed errors must carry the transferId for the settling journal. */
-  stampTransferId(err, transferId) {
-    if (err instanceof SphereError && isPossiblyCommittedSendOutcome(err) && err.transferId === void 0) {
-      err.transferId = transferId;
-    }
-  }
   async softAbort(transferId) {
     try {
       await this.deps.client.abortIntent(transferId);
@@ -4804,57 +5219,11 @@ var PaymentsFacade = class {
     const mintId = this.newId();
     this.activeMoneyOps.add(mintId);
     try {
-      return await this.mintUnderJournal(mintId, coinId, amount);
+      return await runMintUnderJournal(this.mintDeps(), { mintId, coinId, amount });
     } finally {
       this.activeMoneyOps.delete(mintId);
     }
   }
-  async mintUnderJournal(mintId, coinId, amount) {
-    const engine = this.engine();
-    const entry = {
-      mintId,
-      coinId,
-      amount: amount.toString(),
-      tokenId: "",
-      createdAt: this.nowMs()
-    };
-    await this.machineStores.mintJournal.upsert(entry);
-    let token;
-    try {
-      token = await engine.mint(mintParams(this.ownPubkeyBytes, coinId, amount), { transferId: mintId });
-    } catch (err) {
-      this.heartbeat.arm();
-      return { success: false, error: messageOf(err) };
-    }
-    if (token.blob.tokenId !== entry.tokenId) {
-      await this.machineStores.mintJournal.upsert({ ...entry, tokenId: token.blob.tokenId });
-    }
-    try {
-      await this.finalizeMint(engine, mintId, token, coinId, amount.toString());
-    } catch (err) {
-      this.heartbeat.arm();
-      return { success: false, tokenId: token.blob.tokenId, error: messageOf(err) };
-    }
-    return { success: true, tokenId: token.blob.tokenId };
-  }
-  async finalizeMint(engine, mintId, token, coinId, amount) {
-    const bytes = token.blob.token;
-    const digest = bytesToHex(sha256(bytes));
-    const keys = await this.deps.storagePort.uploadBlobs([{ sha256: digest, bytes }]);
-    const key = keys.get(digest);
-    if (key === void 0) {
-      throw new SphereError(`no upload key returned for mint blob ${digest}`, "STORAGE_ERROR");
-    }
-    await this.deps.storagePort.applyDelta({
-      transferId: mintId,
-      spent: [],
-      added: [{ tokenId: token.blob.tokenId, key }]
-    });
-    await this.historyStore.recordMint({ tokenId: token.blob.tokenId, coinId, amount });
-    await this.machineStores.mintJournal.removeByKey(mintId);
-    this.heldStates.set(token.blob.tokenId, (await engine.deliveryKeys(bytes)).stateHash);
-    this.trackTail(this.view.delta());
-  }
   /** @returns how many journal entries were RESOLVED (cleared) — heartbeat progress. */
   async replayMints() {
     let resolved = 0;
@@ -4886,7 +5255,7 @@ var PaymentsFacade = class {
     if (token.blob.tokenId !== entry.tokenId) {
       await this.machineStores.mintJournal.upsert({ ...entry, tokenId: token.blob.tokenId });
     }
-    await this.finalizeMint(engine, entry.mintId, token, entry.coinId, entry.amount);
+    await finalizeMint(this.mintDeps(), entry.mintId, token, entry.coinId, entry.amount);
     return true;
   }
   async tokenInServerInventory(tokenId) {