@unicitylabs/sphere-sdk 0.14.9 → 0.14.11-dev.1

package/dist/index.d.cts

@@ -166,6 +166,8 @@ interface PendingTransfer {
 }
 type ConnectionStatus$1 = 'connected' | 'degraded' | 'offline';
 interface PaymentsV2 {
+    prewarmSend(request: SendRequest): Promise<void>;
+    discardPrewarm(): void;
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
         coinId?: string;

package/dist/index.d.ts

@@ -166,6 +166,8 @@ interface PendingTransfer {
 }
 type ConnectionStatus$1 = 'connected' | 'degraded' | 'offline';
 interface PaymentsV2 {
+    prewarmSend(request: SendRequest): Promise<void>;
+    discardPrewarm(): void;
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
         coinId?: string;

package/dist/index.js

@@ -9234,6 +9234,10 @@ import { StateMask } from "@unicitylabs/state-transition-sdk/lib/transaction/Sta
 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";
@@ -9453,6 +9457,7 @@ async function awaitProofBounded(deps, transaction, signal) {
       deps.client,
       deps.trustBase,
       deps.predicateVerifier,
+      deps.unicityCertificateVerifier,
       transaction,
       signal,
       deps.intervalMs
@@ -9659,7 +9664,7 @@ async function burntTokenFromCheckpoint(deps, storedBytes, reDerivedBurnTx, sour
   }
   let burnCertified;
   try {
-    burnCertified = await reDerivedBurnTx.toCertifiedTransaction(deps.trustBase, deps.predicateVerifier, burnProof);
+    burnCertified = await reDerivedBurnTx.toCertifiedTransaction(deps.trustBase, deps.predicateVerifier, deps.unicityCertificateVerifier, burnProof);
   } catch (err) {
     if (isTrustbaseFailure(err)) {
       throw new CheckpointTrustbaseMismatchError(
@@ -9767,7 +9772,7 @@ var SphereTokenEngine = class {
       "AGGREGATOR_ERROR",
       options
     );
-    const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, proof);
+    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);
   }
@@ -9784,7 +9789,7 @@ var SphereTokenEngine = class {
       "AGGREGATOR_ERROR",
       options
     );
-    const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, proof);
+    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);
   }
@@ -9805,7 +9810,7 @@ var SphereTokenEngine = class {
       "TRANSFER_FAILED",
       options
     );
-    const certified = await transferTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, proof);
+    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);
   }
@@ -9892,7 +9897,7 @@ var SphereTokenEngine = class {
     const burnUnlock = await SignaturePredicateUnlockScript.create(burnTx, this.deps.signingService);
     const burnCert = await CertificationData.fromTransaction(burnTx, burnUnlock);
     const burnProof = await this.submitAndAwaitProof(burnCert, burnTx, "Split burn failed", "TRANSFER_FAILED", ctx.options);
-    const burnCertified = await burnTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, burnProof);
+    const burnCertified = await burnTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, burnProof);
     const burntToken = await ctx.params.token.sdkToken.transfer(burnCertified, this.deps.verificationContext);
     return { burntToken, burnProof };
   }
@@ -9931,7 +9936,7 @@ var SphereTokenEngine = class {
     );
     const certData = await CertificationData.fromMintTransaction(mintTx);
     const proof = await this.submitSplitMintLeg(certData, mintTx, options);
-    const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, proof);
+    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);
   }
@@ -10074,6 +10079,7 @@ var SphereTokenEngine = class {
           client: this.deps.client,
           trustBase: this.deps.trustBase,
           predicateVerifier: this.deps.predicateVerifier,
+          unicityCertificateVerifier: this.deps.unicityCertificateVerifier,
           intervalMs: this.deps.proofPollIntervalMs ?? DEFAULT_PROOF_POLL_INTERVAL_MS
           // #683
         },
@@ -10165,6 +10171,9 @@ async function createSphereTokenEngine(config) {
   }
   const trustBase = RootTrustBase.fromJSON(config.trustBaseJson);
   const predicateVerifier = PredicateVerifierService.create();
+  const unicityCertificateVerifier = new UnicityCertificateVerifier(
+    new UnicitySealQuorumSignaturesVerificationRule(new Secp256k1SignatureVerifier(), new VerifiedSealCache(256))
+  );
   const mintJustificationVerifier = new MintJustificationVerifierService();
   mintJustificationVerifier.register(
     new SplitMintJustificationVerifier(decodeSpherePaymentData)
@@ -10173,10 +10182,12 @@ async function createSphereTokenEngine(config) {
     client: new StateTransitionClient(new AggregatorClient(config.aggregatorUrl, config.apiKey ?? null)),
     trustBase,
     predicateVerifier,
+    unicityCertificateVerifier,
     mintJustificationVerifier,
     verificationContext: new VerificationContext(
       trustBase,
       predicateVerifier,
+      unicityCertificateVerifier,
       mintJustificationVerifier,
       new TokenIssuanceVerifierService(false)
     ),
@@ -12278,6 +12289,90 @@ 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();
+  generation = 0;
+  static key(tokenId, stateHash) {
+    return `${tokenId}:${stateHash}`;
+  }
+  /** Claim the cache for a warm about to start; supersedes any warm already running. */
+  begin() {
+    this.entries.clear();
+    this.generation += 1;
+    return this.generation;
+  }
+  /**
+   * Publish a warm's result, unless it was cancelled or superseded while its
+   * fetch was in flight — a cancel that only cleared what had landed so far
+   * would be undone by the continuation of the very warm it cancelled.
+   */
+  commit(generation, warmed) {
+    if (generation !== this.generation) return;
+    for (const [tokenId, stateHash, bytes] of warmed) {
+      this.entries.set(_PrewarmCache.key(tokenId, stateHash), bytes);
+    }
+  }
+  get(tokenId, stateHash) {
+    if (stateHash === void 0) return void 0;
+    return this.entries.get(_PrewarmCache.key(tokenId, stateHash));
+  }
+  clear() {
+    this.entries.clear();
+    this.generation += 1;
+  }
+  get size() {
+    return this.entries.size;
+  }
+};
+async function warmSendSources(deps, request) {
+  const ids = deps.queue.previewSelection(request);
+  if (ids.length === 0) return;
+  const generation = deps.cache.begin();
+  const at = new Map(ids.map((id) => [id, deps.view.stateHashOf(id)]));
+  let blobs;
+  try {
+    blobs = await deps.storagePort.getBlobs([...ids]);
+  } catch {
+    return;
+  }
+  const warmed = [];
+  for (const [tokenId, bytes] of blobs) {
+    const stateHash = at.get(tokenId);
+    if (stateHash !== void 0) warmed.push([tokenId, stateHash, bytes]);
+  }
+  deps.cache.commit(generation, warmed);
+}
+async function takeSourceBlobs(deps, sourceIds) {
+  const blobs = /* @__PURE__ */ new Map();
+  const missing = [];
+  let trustCache = deps.cache.size > 0;
+  if (trustCache) {
+    try {
+      await deps.view.delta();
+    } catch {
+      trustCache = false;
+    }
+  }
+  for (const tokenId of sourceIds) {
+    const warm = trustCache ? deps.cache.get(tokenId, deps.view.stateHashOf(tokenId)) : void 0;
+    if (warm === void 0) missing.push(tokenId);
+    else blobs.set(tokenId, warm);
+  }
+  deps.cache.clear();
+  if (missing.length > 0) {
+    for (const [tokenId, bytes] of await deps.storagePort.getBlobs(missing)) {
+      blobs.set(tokenId, bytes);
+    }
+  }
+  return blobs;
+}
+
 // modules/payments-v2/inventory/presentation.ts
 function toToken(tokenId, snapshot, asset, registry, flags) {
   const iconUrl = registry.getIconUrl(asset.coinId);
@@ -12364,6 +12459,13 @@ function priceOne(asset, quote) {
     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) {
@@ -12602,6 +12704,15 @@ var InventoryView = class {
     }
     return out;
   }
+  /**
+   * 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
+   * only reusable while the token still sits at the state it was fetched at.
+   */
+  stateHashOf(tokenId) {
+    const entry = this.mirror.get(tokenId);
+    return entry !== void 0 && entry.status === "active" ? entry.stateHash : void 0;
+  }
   tokens(registry, filter) {
     const out = [];
     for (const [tokenId, entry] of this.mirror) {
@@ -13521,6 +13632,31 @@ var SpendQueue = class {
     }
     return { kind: "queued", settled: this.enqueue(reservationId, request.coinId, amount) };
   }
+  /**
+   * 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
+   * looking at the confirm screen.
+   *
+   * Deliberately side-effect free: reserving here would pin the user's balance
+   * across think-time and strand it if they never press send. The consequence is
+   * that the real `plan()` may pick differently (inventory moves, another send
+   * reserves first); callers must treat the result as a HINT and tolerate a miss,
+   * never as a commitment that these sources will be spent.
+   */
+  previewSelection(request) {
+    if (this.destroyed) return [];
+    let amount;
+    try {
+      amount = parseAmount(request.amount);
+    } catch {
+      return [];
+    }
+    const { freeView, freeTotal } = this.freeView(request.coinId);
+    if (freeTotal < amount) return [];
+    const plan = selectCoins(freeView, amount, { workBudget: this.deps.workBudget });
+    if (plan === null) return [];
+    return [...plan.direct, ...plan.split !== void 0 ? [plan.split.tokenId] : []];
+  }
   // Coverage math: free + Σ declared expected change of in-flight sends —
   // never the full amount of in-flight sources (§5.3).
   declareExpectedChange(transferId, coinId, amount) {
@@ -13870,6 +14006,7 @@ var PaymentsFacade = class {
       now: () => this.nowMs()
     });
   }
+  prewarmed = new PrewarmCache();
   view;
   ledger;
   queue;
@@ -13963,6 +14100,15 @@ var PaymentsFacade = class {
     return derivePendingTransfers(this.machineStores, this.machineDeps.decryptPayload);
   }
   // ── money movement ─────────────────────────────────────────────────────────
+  async prewarmSend(request) {
+    await warmSendSources(this.warmDeps(), request);
+  }
+  discardPrewarm() {
+    this.prewarmed.clear();
+  }
+  warmDeps() {
+    return { queue: this.queue, view: this.view, storagePort: this.deps.storagePort, cache: this.prewarmed };
+  }
   send(request) {
     return this.track(this.sendOutcome(request));
   }
@@ -14172,7 +14318,7 @@ var PaymentsFacade = class {
   }
   async materialize(transferId, recipientPubkey, request, spend, sourceIds) {
     const engine = this.engine();
-    const blobs = await this.deps.storagePort.getBlobs([...sourceIds]);
+    const blobs = await takeSourceBlobs(this.warmDeps(), sourceIds);
     const sources = /* @__PURE__ */ new Map();
     const sourceTokens = [];
     const spentStates = {};
@@ -14185,7 +14331,7 @@ var PaymentsFacade = class {
       const keys = await engine.deliveryKeys(bytes);
       spentStates[tokenId] = { local: keys.stateHash, protocol: keys.stateHash };
       sources.set(tokenId, token);
-      sourceTokens.push(this.toUiToken(tokenId, request.coinId, engine.balanceOf(token, request.coinId)));
+      sourceTokens.push(transferringToken(tokenId, request.coinId, engine.balanceOf(token, request.coinId), this.deps.registry, this.nowMs()));
     }
     const payload = buildPayload(recipientPubkey, request, spend, spentStates);
     const plan = {
@@ -14329,7 +14475,7 @@ var PaymentsFacade = class {
     await this.machineStores.mintJournal.upsert(entry);
     let token;
     try {
-      token = await engine.mint(this.mintParams(coinId, amount), { transferId: mintId });
+      token = await engine.mint(mintParams(this.ownPubkeyBytes, coinId, amount), { transferId: mintId });
     } catch (err) {
       this.heartbeat.arm();
       return { success: false, error: messageOf(err) };
@@ -14388,7 +14534,7 @@ var PaymentsFacade = class {
       });
       return false;
     }
-    const token = await engine.mint(this.mintParams(entry.coinId, BigInt(entry.amount)), {
+    const token = await engine.mint(mintParams(this.ownPubkeyBytes, entry.coinId, BigInt(entry.amount)), {
       transferId: entry.mintId
     });
     if (token.blob.tokenId !== entry.tokenId) {
@@ -14397,12 +14543,6 @@ var PaymentsFacade = class {
     await this.finalizeMint(engine, entry.mintId, token, entry.coinId, entry.amount);
     return true;
   }
-  mintParams(coinId, amount) {
-    return {
-      recipientPubkey: this.ownPubkeyBytes,
-      value: { assets: [{ coinId, amount }] }
-    };
-  }
   async tokenInServerInventory(tokenId) {
     let page = await this.deps.storagePort.listInventory();
     for (let i = 0; i < INVENTORY_SCAN_PAGE_LIMIT; i++) {
@@ -14431,12 +14571,6 @@ var PaymentsFacade = class {
       page = await this.deps.storagePort.listInventory(page.cursor);
     }
   }
-  toUiToken(tokenId, coinId, amount) {
-    const now = this.nowMs();
-    const snapshot = { assets: [], createdAt: now, updatedAt: now };
-    const flags = { transferring: true, suspectedSpent: false };
-    return toToken(tokenId, snapshot, { coinId, amount: amount.toString() }, this.deps.registry, flags);
-  }
   track(op) {
     const settled = op.then(() => void 0, () => void 0);
     this.pendingOps.add(settled);