@unicitylabs/sphere-sdk 0.17.0 → 0.17.1

package/dist/index.d.cts

@@ -88,7 +88,7 @@ interface SendRequest {
     coinId: string;
     memo?: string;
 }
-interface SendCoinlessRequest {
+interface SendWholeTokenRequest {
     recipient: string;
     tokenId: string;
     memo?: string;
@@ -186,7 +186,9 @@ interface PaymentsV2 {
         limit?: number;
     }): Promise<HistoryPage>;
     send(req: SendRequest): Promise<TransferResult>;
-    sendCoinless(req: SendCoinlessRequest): Promise<TransferResult>;
+    sendWholeToken(req: SendWholeTokenRequest): Promise<TransferResult>;
+    /** NFT-scoped twin: refuses a valued source. Connect's `send_nft` routes here. */
+    sendCoinless(req: SendWholeTokenRequest): Promise<TransferResult>;
     mint(coinId: string, amount: bigint): Promise<MintResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];

package/dist/index.d.ts

@@ -88,7 +88,7 @@ interface SendRequest {
     coinId: string;
     memo?: string;
 }
-interface SendCoinlessRequest {
+interface SendWholeTokenRequest {
     recipient: string;
     tokenId: string;
     memo?: string;
@@ -186,7 +186,9 @@ interface PaymentsV2 {
         limit?: number;
     }): Promise<HistoryPage>;
     send(req: SendRequest): Promise<TransferResult>;
-    sendCoinless(req: SendCoinlessRequest): Promise<TransferResult>;
+    sendWholeToken(req: SendWholeTokenRequest): Promise<TransferResult>;
+    /** NFT-scoped twin: refuses a valued source. Connect's `send_nft` routes here. */
+    sendCoinless(req: SendWholeTokenRequest): Promise<TransferResult>;
     mint(coinId: string, amount: bigint): Promise<MintResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];

package/dist/index.js

@@ -11821,6 +11821,9 @@ 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;
 }
@@ -12189,7 +12192,14 @@ var TransferMachine = class {
     try {
       const coinId = coinIdOf(payload);
       const committedAmount = coinId === void 0 ? "0" : await this.settledAmount(engine, coinId, committed);
-      await this.deps.recordHistory?.({ transferId, payload, phase, committedAmount });
+      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 {
@@ -12203,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) {
@@ -12342,7 +12364,7 @@ async function runOne(ctx, job, report) {
       report.failed.push(job.transferId);
       return;
     }
-    if (job.payload.kind === "coinless" && !isCoinlessEnvelope(token.valueEnvelope)) {
+    if (isWholeIntent(job.payload) && token.valueEnvelope === "bare_collection") {
       logger.warn(
         "PaymentsV2",
         `resume: token intent ${job.transferId} names a source carrying coin value \u2014 refusing`
@@ -12390,7 +12412,7 @@ function validateCoinPayload(c) {
   }
   return { ...c, kind: "coin" };
 }
-function validateCoinlessPayload(p) {
+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",
@@ -12400,7 +12422,7 @@ function validateCoinlessPayload(p) {
   if (p.split !== void 0) {
     throw new SphereError("token intent payload cannot carry a split", "VALIDATION_ERROR");
   }
-  return { ...p, kind: "coinless", direct: [p.direct[0]] };
+  return { ...p, kind: "whole", direct: [p.direct[0]] };
 }
 function validatePayload(raw) {
   const p = raw !== null && typeof raw === "object" ? raw : null;
@@ -12414,13 +12436,13 @@ function validatePayload(raw) {
     throw new SphereError("intent payload is missing recipient", "VALIDATION_ERROR");
   }
   const kind = p.kind ?? "coin";
-  if (kind !== "coin" && kind !== "coinless") {
+  if (kind !== "coin" && kind !== "whole" && kind !== "coinless") {
     throw new SphereError(
       `unsupported intent kind '${String(kind)}' \u2014 not resumable by this client`,
       "VALIDATION_ERROR"
     );
   }
-  return kind === "coinless" ? validateCoinlessPayload(p) : validateCoinPayload(p);
+  return kind === "coin" ? validateCoinPayload(p) : validateWholePayload(p);
 }
 
 // modules/payments-v2/convergence.ts
@@ -12633,8 +12655,9 @@ async function openRow(entry, journal, decryptPayload) {
   };
 }
 function subject(payload) {
-  if (payload?.kind === "coinless") {
-    const tokenId = payload.direct?.[0];
+  const rawKind = payload?.kind;
+  if (rawKind === "whole" || rawKind === "coinless") {
+    const tokenId = payload?.direct?.[0];
     return { coinId: "", amount: "", ...typeof tokenId === "string" ? { tokenId } : {} };
   }
   const coin = payload;
@@ -12707,10 +12730,10 @@ function buildPayload(recipientPubkey, request, spend, spentStates) {
 function messageOf(err) {
   return err instanceof Error ? err.message : String(err);
 }
-function buildCoinlessPayload(recipientPubkey, request, spentStates) {
+function buildWholePayload(recipientPubkey, request, spentStates) {
   return {
     v: 2,
-    kind: "coinless",
+    kind: "whole",
     recipient: recipientPubkey,
     ...request.memo !== void 0 ? { memo: request.memo } : {},
     direct: [request.tokenId],
@@ -12779,8 +12802,102 @@ async function finalizeMint(deps, mintId, token, coinId, amount) {
   deps.refreshView();
 }
 
-// modules/payments-v2/send-coinless.ts
-async function materializeCoinlessSpend(deps, input) {
+// 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);
@@ -12788,14 +12905,20 @@ async function materializeCoinlessSpend(deps, input) {
     throw new SphereError(`Selected source ${tokenId} has no blob in storage`, "STORAGE_ERROR");
   }
   const token = await engine.decodeToken({ tokenId, token: bytes });
-  if (!isCoinlessEnvelope(token.valueEnvelope)) {
+  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 send()`,
+      `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 = buildCoinlessPayload(input.recipientPubkey, input.request, {
+  const payload = buildWholePayload(input.recipientPubkey, input.request, {
     [tokenId]: { local: keys.stateHash, protocol: keys.stateHash }
   });
   const plan = {
@@ -12806,7 +12929,10 @@ async function materializeCoinlessSpend(deps, input) {
     sources: /* @__PURE__ */ new Map([[tokenId, token]]),
     ...input.request.memo !== void 0 ? { memo: input.request.memo } : {}
   };
-  return { transferId: input.transferId, coinId: "", plan, sourceIds: input.sourceIds, sourceTokens: [] };
+  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
@@ -12953,100 +13079,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/history/History.ts
 function wireAssets(assets) {
   return assets.map((a) => ({ coinId: a.coinId, amount: a.amount }));
@@ -13302,10 +13334,10 @@ var InventoryView = class {
     if (this.inFlight.has(tokenId) && !this.pinned(tokenId)) return false;
     return !this.suspected.has(stateKey(tokenId, entry.stateHash));
   }
-  /** #777: is this NAMED token a spendable COINLESS holding? Never a coin source. */
-  spendableCoinless(tokenId) {
+  /** Is this NAMED token spendable whole — coinless or valued (#777)? */
+  spendableToken(tokenId) {
     const entry = this.mirror.get(tokenId);
-    return entry !== void 0 && entry.coinless && this.isSpendable(tokenId, entry);
+    return entry !== void 0 && this.isSpendable(tokenId, entry);
   }
   /**
    * Current mirrored state of an ACTIVE token, or undefined when it is unknown
@@ -13678,7 +13710,7 @@ async function screen(deps, engine, entry) {
       tokenId: keys.tokenId,
       stateHash: keys.stateHash,
       assets: toAssetAmounts(token),
-      ...isCoinlessEnvelope2(token.valueEnvelope) ? { tokenType: token.tokenType } : {}
+      ...isCoinlessEnvelope(token.valueEnvelope) ? { tokenType: token.tokenType } : {}
     }
   };
 }
@@ -13815,9 +13847,6 @@ function claimAck(entry) {
 function rejectAck(entry, reason) {
   return { deliveryId: entry.deliveryId, disposition: "rejected", reason, cursor: entry.cursor };
 }
-function isCoinlessEnvelope2(envelope) {
-  return envelope.startsWith("none_");
-}
 function toAssetAmounts(token) {
   return (token.value?.assets ?? []).map((asset) => ({
     coinId: asset.coinId,
@@ -14392,7 +14421,7 @@ var SpendQueue = class {
    * can release, so queueing would block until a timeout on a spend that cannot
    * become possible.
    */
-  planCoinless(reservationId, tokenId) {
+  planWhole(reservationId, tokenId) {
     if (this.destroyed) {
       throw new SphereError("Module has been destroyed", "MODULE_DESTROYED");
     }
@@ -14400,11 +14429,8 @@ var SpendQueue = class {
     if (unproven !== null) {
       throw new SphereError(`Cannot spend yet: ${unproven}`, "SEND_SYNC_PENDING");
     }
-    if (this.deps.spendableCoinless?.(tokenId) !== true) {
-      throw new SphereError(
-        `Token ${tokenId} is not a spendable coinless holding`,
-        "VALIDATION_ERROR"
-      );
+    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) {
@@ -14605,7 +14631,7 @@ function composeFacadeParts(deps, hooks) {
   const queue = new SpendQueue({
     ledger,
     getPool: (coinId) => view.pool(coinId),
-    spendableCoinless: (tokenId) => view.spendableCoinless(tokenId),
+    spendableToken: (tokenId) => view.spendableToken(tokenId),
     ...deps.workBudget !== void 0 ? { workBudget: deps.workBudget } : {}
   });
   const historyStore = new History({
@@ -14686,12 +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,
         // §5.9: the SETTLED amount, never payload.amount — the plan. A token
         // spend moved no coin: `assets: []` + tokenId (wallet-api#151 / §10).
-        ...payload.kind === "coinless" ? { assets: [], tokenId: payload.direct[0] } : { assets: [{ coinId: payload.coinId, amount: committedAmount }] },
+        ...isWholeIntent(payload) ? { assets: committedAssets ?? [], tokenId: payload.direct[0] } : { assets: [{ coinId: payload.coinId, amount: committedAmount }] },
         recipientPubkey: payload.recipient,
         ...payload.memo !== void 0 ? { memo: payload.memo } : {}
       });
@@ -14906,10 +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.sendCoinlessOutcome(request));
+    return this.track(this.runJob({ kind: "whole", request, requireCoinless: true }, "0"));
   }
   async receive() {
     const transfers = await this.track(this.receiveLoop.drainOnce());
@@ -14957,13 +14987,6 @@ var PaymentsFacade = class {
   // ── 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). */
-  sendOutcome(request) {
-    return this.runJob({ kind: "coin", request }, request.amount);
-  }
-  /** A token spend has no amount; '0' keeps the shortfall arithmetic total-free. */
-  sendCoinlessOutcome(request) {
-    return this.runJob({ kind: "coinless", request }, "0");
-  }
   async runJob(job, amount) {
     const run = {
       amount,
@@ -15008,7 +15031,7 @@ var PaymentsFacade = class {
       const disposition = await this.runAttempt(ctx);
       if (disposition.kind === "rethrow") throw partialize(disposition.error, run);
       if (disposition.kind === "retry-full") {
-        if (job.kind === "coinless" || attempt >= MAX_RESELECT) throw partialize(disposition.error, run);
+        if (job.kind === "whole" || attempt >= MAX_RESELECT) throw partialize(disposition.error, run);
         continue;
       }
       if (disposition.kind === "success") {
@@ -15112,13 +15135,19 @@ var PaymentsFacade = class {
   async planAndMaterialize(recipientPubkey, job, run) {
     const transferId = this.newId();
     run.lastTransferId = transferId;
-    if (job.kind === "coinless") {
-      const spend2 = this.queue.planCoinless(transferId, job.request.tokenId);
+    if (job.kind === "whole") {
+      const spend2 = this.queue.planWhole(transferId, job.request.tokenId);
       const sourceIds2 = this.markPlanned(transferId, "", spend2);
       try {
-        return await materializeCoinlessSpend(
-          { engine: this.engine(), storagePort: this.deps.storagePort },
-          { transferId, recipientPubkey, request: job.request, sourceIds: sourceIds2 }
+        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);