@unicitylabs/sphere-sdk 0.16.0 → 0.17.1

package/dist/index.js

@@ -8146,6 +8146,8 @@ var FETCH_TIMEOUT_MS = 1e4;
 var TokenRegistry = class _TokenRegistry {
   static instance = null;
   definitionsById;
+  /** Non-fungible definitions keyed by TOKEN TYPE — a separate namespace (#147). */
+  definitionsByType;
   definitionsBySymbol;
   definitionsByName;
   // Remote refresh state
@@ -8164,6 +8166,7 @@ var TokenRegistry = class _TokenRegistry {
   inFlight = null;
   constructor() {
     this.definitionsById = /* @__PURE__ */ new Map();
+    this.definitionsByType = /* @__PURE__ */ new Map();
     this.definitionsBySymbol = /* @__PURE__ */ new Map();
     this.definitionsByName = /* @__PURE__ */ new Map();
   }
@@ -8391,9 +8394,11 @@ var TokenRegistry = class _TokenRegistry {
     this.definitionsById.clear();
     this.definitionsBySymbol.clear();
     this.definitionsByName.clear();
+    this.definitionsByType.clear();
     for (const def of definitions) {
       const idLower = def.id.toLowerCase();
       this.definitionsById.set(idLower, def);
+      if (def.assetKind === "non-fungible") this.definitionsByType.set(idLower, def);
       if (def.symbol) {
         this.definitionsBySymbol.set(def.symbol.toUpperCase(), def);
       }
@@ -8607,6 +8612,20 @@ var TokenRegistry = class _TokenRegistry {
   getAllDefinitions() {
     return Array.from(this.definitionsById.values());
   }
+  /**
+   * Definition for a coinless token's genesis TOKEN TYPE (#777). Never falls back
+   * to `getDefinition`: a type and a coin id live in different namespaces, so a
+   * type that collided with a coin id would otherwise render as that coin.
+   */
+  getTypeMeta(tokenType) {
+    const def = this.getTypeDefinition(tokenType);
+    if (!def) return null;
+    return { name: def.name, iconUrl: def.icons?.[0]?.url ?? null };
+  }
+  getTypeDefinition(tokenType) {
+    if (!tokenType) return void 0;
+    return this.definitionsByType.get(tokenType.toLowerCase());
+  }
   /**
    * Get all fungible token definitions
    * @returns Array of fungible token definitions
@@ -9441,6 +9460,8 @@ import { DataHasherFactory } from "@unicitylabs/state-transition-sdk/lib/crypto/
 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";
@@ -9853,6 +9874,126 @@ async function burntTokenFromCheckpoint(deps, storedBytes, reDerivedBurnTx, sour
   return burntToken;
 }
 
+// token-engine/value-envelope.ts
+function isCoinlessEnvelope(envelope) {
+  return envelope.startsWith("none_");
+}
+var SELF_DESCRIBED_CBOR_TAG = 55799n;
+var CBOR_MAJOR_TYPE_MASK = 224;
+var describe = (error) => error instanceof Error ? error.message : String(error);
+var invalid = (message) => new SphereError(message, "VALIDATION_ERROR");
+function majorTypeOf(bytes) {
+  const first = bytes.at(0);
+  return first === void 0 ? null : first & CBOR_MAJOR_TYPE_MASK;
+}
+function headTagNumber(bytes) {
+  try {
+    return new CborReader(bytes).readLength(MajorType.TAG);
+  } catch {
+    return null;
+  }
+}
+function isAssetShaped(item) {
+  try {
+    return CborDeserializer.decodeArray(item, 2).every(
+      (field) => majorTypeOf(field) === MajorType.BYTE_STRING
+    );
+  } catch {
+    return false;
+  }
+}
+function arrayItemsOrNull(bytes) {
+  try {
+    return CborDeserializer.decodeArray(bytes);
+  } catch {
+    return null;
+  }
+}
+function decodeSphere(genesisData) {
+  try {
+    return SpherePaymentData.fromCBOR(genesisData).toValue();
+  } catch (error) {
+    throw invalid(`Failed to decode token payment data: ${describe(error)}`);
+  }
+}
+function taggedItemBody(genesisData) {
+  try {
+    return CborDeserializer.decodeTag(genesisData).data;
+  } catch (error) {
+    throw invalid(
+      `Token value payload is a CBOR tag whose item is malformed or carries trailing bytes: ${describe(error)}`
+    );
+  }
+}
+function selfDescribedBodyCarriesValue(body) {
+  const major = majorTypeOf(body);
+  if (major === MajorType.TAG) {
+    const inner = headTagNumber(body);
+    return inner === SpherePaymentData.CBOR_TAG || inner === SELF_DESCRIBED_CBOR_TAG;
+  }
+  if (major === MajorType.ARRAY) {
+    const items = arrayItemsOrNull(body);
+    return items !== null && items.some(isAssetShaped);
+  }
+  return false;
+}
+function classifyTagged(genesisData) {
+  const tag = headTagNumber(genesisData);
+  if (tag === null) {
+    throw invalid(
+      "Token value payload has an unreadable or non-canonically encoded CBOR tag head \u2014 it could be a malformed SpherePaymentData envelope"
+    );
+  }
+  if (tag === SpherePaymentData.CBOR_TAG) {
+    return { envelope: "sphere", value: decodeSphere(genesisData) };
+  }
+  const body = taggedItemBody(genesisData);
+  if (tag === SELF_DESCRIBED_CBOR_TAG && selfDescribedBodyCarriesValue(body)) {
+    throw invalid(
+      "Token value payload is a value envelope wrapped in the self-described CBOR tag 55799 (RFC 8949 \xA73.4.6), which no codec here unwraps \u2014 its coins would be invisible. Emit the envelope without the self-describe prefix"
+    );
+  }
+  return { envelope: "none_tag", value: null };
+}
+function classifyArray(genesisData) {
+  const items = arrayItemsOrNull(genesisData);
+  if (items === null) {
+    throw invalid("Token value payload is not PaymentAssetCollection: malformed CBOR array");
+  }
+  return items.some(isAssetShaped) ? { envelope: "bare_collection", value: null } : { envelope: "none_other", value: null };
+}
+function classifyValueEnvelope(genesisData) {
+  if (genesisData === null) return { envelope: "none_absent", value: null };
+  const major = majorTypeOf(genesisData);
+  if (major === null) return { envelope: "none_absent", value: null };
+  if (major === MajorType.TAG) return classifyTagged(genesisData);
+  if (major === MajorType.ARRAY) return classifyArray(genesisData);
+  return { envelope: "none_other", value: null };
+}
+function wrapToken(sdkToken) {
+  const { envelope, value } = classifyValueEnvelope(sdkToken.genesis.data);
+  const blob = {
+    tokenId: HexConverter.encode(sdkToken.id.bytes),
+    token: sdkToken.toCBOR()
+  };
+  return {
+    sdkToken,
+    blob,
+    value,
+    valueEnvelope: envelope,
+    tokenType: HexConverter.encode(sdkToken.type.bytes)
+  };
+}
+function assertMintableData(data) {
+  try {
+    classifyValueEnvelope(data);
+  } catch (error) {
+    throw invalid(
+      `Cannot mint a data token with this payload: ${describe(error)}. Raw bytes starting in the CBOR array (0x80-0x9f) or tag (0xc0-0xdf) range must be well-formed canonical CBOR; wrap them in a CBOR byte string, map, text string, or a tag other than 39050/55799.`
+    );
+  }
+}
+
 // token-engine/SphereTokenEngine.ts
 var DEFAULT_PROOF_POLL_INTERVAL_MS = 300;
 var MAX_MINT_CONCURRENCY = 8;
@@ -9909,7 +10050,7 @@ var SphereTokenEngine = class {
       return sdkToken.latestTransaction.data;
     }
     const data = sdkToken.genesis.data;
-    if (data && this.isSpherePaymentData(data)) {
+    if (data && classifyValueEnvelope(data).envelope === "sphere") {
       return SpherePaymentData.fromCBOR(data).memo;
     }
     return null;
@@ -9939,9 +10080,10 @@ var SphereTokenEngine = class {
     );
     const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
     const token = await Token.mint(certified, this.deps.verificationContext);
-    return this.wrapToken(token);
+    return wrapToken(token);
   }
   async mintDataToken(params, options) {
+    assertMintableData(params.data);
     const recipient = SignaturePredicate.create(params.recipientPubkey);
     const tokenType = params.tokenType ? new TokenType(params.tokenType) : TokenType.generate();
     const salt = params.salt ? TokenSalt.fromBytes(params.salt) : TokenSalt.generate();
@@ -9956,7 +10098,7 @@ var SphereTokenEngine = class {
     );
     const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
     const token = await Token.mint(certified, this.deps.verificationContext);
-    return this.wrapToken(token);
+    return wrapToken(token);
   }
   async transfer(params, options) {
     this.assertOwned(params.token);
@@ -9979,13 +10121,19 @@ var SphereTokenEngine = class {
     );
     const certified = await transferTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
     const transferred = await params.token.sdkToken.transfer(certified, this.deps.verificationContext);
-    return this.wrapToken(transferred);
+    return wrapToken(transferred);
   }
   async split(params, options) {
     this.assertOwned(params.token);
     if (params.outputs.length === 0) {
       throw new SphereError("Split requires at least one output", "VALIDATION_ERROR");
     }
+    if (params.token.value === null) {
+      throw new SphereError(
+        `Cannot split token ${params.token.blob.tokenId}: its genesis payload carries no value this SDK can read (envelope: ${params.token.valueEnvelope}). A coinless token can only be transferred whole.`,
+        "VALIDATION_ERROR"
+      );
+    }
     const transferId = this.resolveTransferId(options);
     const requests = params.outputs.map(
       (o, i) => SplitTokenRequest.create(
@@ -10107,7 +10255,7 @@ var SphereTokenEngine = class {
     const proof = await this.submitSplitMintLeg(certData, mintTx, options);
     const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
     const token = await Token.mint(certified, this.deps.verificationContext);
-    return this.wrapToken(token);
+    return wrapToken(token);
   }
   /**
    * Submit one split-mint leg. A `TRANSACTION_HASH_MISMATCH` on a mint leg is NOT a foreign spend
@@ -10165,7 +10313,7 @@ var SphereTokenEngine = class {
         "VALIDATION_ERROR"
       );
     }
-    return this.wrapToken(sdkToken);
+    return wrapToken(sdkToken);
   }
   // ── internals ────────────────────────────────────────────────────────────────
   /**
@@ -10277,34 +10425,6 @@ var SphereTokenEngine = class {
       throw new SphereError("Cannot transfer a token not owned by this engine identity", "VALIDATION_ERROR");
     }
   }
-  /** Wrap an SDK token into a SphereToken: cache its blob (incl. stable tokenId) + decoded value. */
-  wrapToken(sdkToken) {
-    const data = sdkToken.genesis.data;
-    let value = null;
-    if (data && this.isSpherePaymentData(data)) {
-      try {
-        value = SpherePaymentData.fromCBOR(data).toValue();
-      } catch (err) {
-        throw new SphereError(
-          `Failed to decode token payment data: ${err instanceof Error ? err.message : String(err)}`,
-          "VALIDATION_ERROR"
-        );
-      }
-    }
-    const blob = {
-      tokenId: HexConverter.encode(sdkToken.id.bytes),
-      token: sdkToken.toCBOR()
-    };
-    return { sdkToken, blob, value };
-  }
-  /** True if the bytes are a SpherePaymentData envelope (value token) vs a raw data token. */
-  isSpherePaymentData(data) {
-    try {
-      return CborDeserializer.decodeTag(data).tag === SpherePaymentData.CBOR_TAG;
-    } catch {
-      return false;
-    }
-  }
   /**
    * Terminate the verification worker pool, if this engine was configured with
    * one. Idempotent — the pool's dispose only touches workers it spawned.
@@ -11700,6 +11820,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;
+}
+
 // modules/payments-v2/machine/TransferMachine.ts
 var CERTIFY_WIDTH = 20;
 var KEEP_OPEN_CODES = /* @__PURE__ */ new Set([
@@ -11902,13 +12033,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
@@ -12030,7 +12162,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()
@@ -12056,8 +12190,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 {
@@ -12071,6 +12213,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) {
@@ -12099,8 +12253,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
@@ -12207,6 +12364,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 {
@@ -12237,6 +12402,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")) {
@@ -12245,14 +12432,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
@@ -12458,13 +12648,24 @@ async function openRow(entry, journal, decryptPayload) {
     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 : "",
+    ...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 {
@@ -12494,6 +12695,263 @@ 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 = bytesToHex3(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 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/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 };
+}
+
+// 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
 var ATTENTION_RECIPIENT_NETWORK_UNVERIFIED = "recipient:network-unverified";
 async function requireSameNetworkRecipient(deps, identifier) {
@@ -12542,11 +13000,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();
@@ -12626,124 +13079,15 @@ 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
-  };
+// modules/payments-v2/history/History.ts
+function wireAssets(assets) {
+  return assets.map((a) => ({ coinId: a.coinId, amount: a.amount }));
 }
-function messageOf(err) {
-  return err instanceof Error ? err.message : String(err);
+function isPermanentReject(err) {
+  const status = err?.status;
+  if (typeof status !== "number") return false;
+  return status >= 400 && status < 500 && status !== 408 && status !== 429;
 }
-
-// modules/payments-v2/history/History.ts
 var WIRE_TOKEN_ID = /^(?:[0-9a-f]{2}){1,64}$/;
 var WIRE_PUBKEY = /^0[23][0-9a-f]{64}$/;
 var History = class {
@@ -12768,7 +13112,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),
@@ -12781,7 +13125,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),
@@ -12794,7 +13138,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)
     }));
@@ -12805,7 +13149,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));
@@ -12872,6 +13219,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;
@@ -12965,14 +13319,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
@@ -12998,6 +13364,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;
@@ -13069,14 +13458,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
     });
@@ -13312,7 +13706,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) {
@@ -13323,6 +13722,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 } : {},
@@ -13336,6 +13736,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
   };
@@ -14001,6 +14414,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
@@ -14190,6 +14631,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({
@@ -14270,13 +14712,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 } : {}
       });
@@ -14311,12 +14752,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 } : {},
@@ -14464,6 +14903,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 ?? {});
   }
@@ -14486,7 +14932,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());
@@ -14518,12 +14971,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: [],
@@ -14533,7 +14999,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;
@@ -14553,19 +15019,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") {
@@ -14621,7 +15087,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);
@@ -14655,7 +15121,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") {
@@ -14666,9 +15132,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);
@@ -14802,22 +15288,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);
@@ -14833,57 +15303,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 = bytesToHex3(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;
@@ -14915,7 +15339,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) {