@unicitylabs/sphere-sdk 0.14.11-dev.8 → 0.15.0-dev.1

package/dist/core/index.cjs

@@ -9471,7 +9471,15 @@ function resolveProofTimeoutMs(configured) {
   return configured;
 }
 var TRANSIENT_HTTP_STATUSES = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
+var TransientSubmitAnswer = class extends Error {
+  constructor(status) {
+    super(`gateway is not ready to certify yet (${status})`);
+    this.status = status;
+    this.name = "TransientSubmitAnswer";
+  }
+};
 function isTransientGatewayError(err) {
+  if (err instanceof TransientSubmitAnswer) return true;
   return err instanceof import_JsonRpcNetworkError.JsonRpcNetworkError && TRANSIENT_HTTP_STATUSES.has(err.status);
 }
 function pause(ms, signal) {
@@ -9592,37 +9600,9 @@ function certificationFailure(err, failLabel, submitError, submitRejectedCleanly
   );
 }
 
-// token-engine/token-blob.ts
-var TOKEN_BLOB_TAG = 39051n;
-var TOKEN_BLOB_VERSION = 1;
-function decodeTokenBlob(bytes) {
-  const tag = import_CborDeserializer.CborDeserializer.decodeTag(bytes);
-  if (tag.tag !== TOKEN_BLOB_TAG) {
-    throw new import_CborError.CborError(`Invalid TokenBlob tag: ${tag.tag}`);
-  }
-  const fields = import_CborDeserializer.CborDeserializer.decodeArray(tag.data, 4);
-  const v = Number(import_CborDeserializer.CborDeserializer.decodeUnsignedInteger(fields[0]));
-  if (v !== TOKEN_BLOB_VERSION) {
-    throw new import_CborError.CborError(`Unsupported TokenBlob version: ${v}`);
-  }
-  return {
-    v,
-    network: Number(import_CborDeserializer.CborDeserializer.decodeUnsignedInteger(fields[1])),
-    tokenId: import_CborDeserializer.CborDeserializer.decodeTextString(fields[2]),
-    token: import_CborDeserializer.CborDeserializer.decodeByteString(fields[3])
-  };
-}
-function unwrapTokenBlobBytes(bytes) {
-  try {
-    return decodeTokenBlob(bytes).token;
-  } catch {
-    return bytes;
-  }
-}
-
 // token-engine/blob-keys.ts
 async function deriveDeliveryKeys(blobBytes) {
-  const token = await import_Token.Token.fromCBOR(unwrapTokenBlobBytes(blobBytes));
+  const token = await import_Token.Token.fromCBOR(blobBytes);
   const stateHash = import_HexConverter.HexConverter.encode((await token.latestTransaction.calculateStateHash()).imprint);
   return { tokenId: import_HexConverter.HexConverter.encode(token.id.bytes), stateHash };
 }
@@ -9676,8 +9656,8 @@ function deriveRealization(privKeyHex, transferId, index, field) {
 }
 
 // token-engine/split-checkpoint.ts
-var CHECKPOINT_VERSION = 1;
-var CHECKPOINT_SDK_VERSION = "@unicitylabs/state-transition-sdk@2.0.2";
+var CHECKPOINT_VERSION = 2;
+var CHECKPOINT_SDK_VERSION = "@unicitylabs/state-transition-sdk@3.0.1";
 function bytesEqual(a, b) {
   if (a.length !== b.length) return false;
   for (let i = 0; i < a.length; i++) {
@@ -9827,13 +9807,11 @@ var SphereTokenEngine = class {
     const data = params.value ? await SpherePaymentData.fromValue(params.value).encode() : null;
     const transferId = this.resolveTransferId(options);
     const opIndex = this.resolveOpIndex(options);
-    const mintTx = await import_MintTransaction.MintTransaction.create(
-      this.deps.networkId,
-      recipient,
+    const mintTx = await import_MintTransaction.MintTransaction.create(this.deps.networkId, recipient, {
       data,
-      new import_TokenType.TokenType(deriveRealization(this.privateKeyHex, transferId, opIndex, "tokenType")),
-      import_TokenSalt.TokenSalt.fromBytes(deriveRealization(this.privateKeyHex, transferId, opIndex, "mint"))
-    );
+      tokenType: new import_TokenType.TokenType(deriveRealization(this.privateKeyHex, transferId, opIndex, "tokenType")),
+      salt: import_TokenSalt.TokenSalt.fromBytes(deriveRealization(this.privateKeyHex, transferId, opIndex, "mint"))
+    });
     const certificationData = await import_CertificationData.CertificationData.fromMintTransaction(mintTx);
     const proof = await this.submitAndAwaitProof(
       certificationData,
@@ -9850,7 +9828,7 @@ var SphereTokenEngine = class {
     const recipient = import_SignaturePredicate.SignaturePredicate.create(params.recipientPubkey);
     const tokenType = params.tokenType ? new import_TokenType.TokenType(params.tokenType) : import_TokenType.TokenType.generate();
     const salt = params.salt ? import_TokenSalt.TokenSalt.fromBytes(params.salt) : import_TokenSalt.TokenSalt.generate();
-    const mintTx = await import_MintTransaction.MintTransaction.create(this.deps.networkId, recipient, params.data, tokenType, salt);
+    const mintTx = await import_MintTransaction.MintTransaction.create(this.deps.networkId, recipient, { data: params.data, tokenType, salt });
     const certificationData = await import_CertificationData.CertificationData.fromMintTransaction(mintTx);
     const proof = await this.submitAndAwaitProof(
       certificationData,
@@ -9870,7 +9848,9 @@ var SphereTokenEngine = class {
     const stateMask = import_StateMask.StateMask.fromBytes(
       deriveRealization(this.privateKeyHex, transferId, this.resolveOpIndex(options), "stateMask")
     );
-    const transferTx = await import_TransferTransaction.TransferTransaction.create(params.token.sdkToken, recipient, stateMask, params.data ?? null);
+    const transferTx = await import_TransferTransaction.TransferTransaction.create(params.token.sdkToken, recipient, stateMask, {
+      data: params.data ?? null
+    });
     const unlockScript = await import_SignaturePredicateUnlockScript.SignaturePredicateUnlockScript.create(transferTx, this.deps.signingService);
     const certificationData = await import_CertificationData.CertificationData.fromTransaction(transferTx, unlockScript);
     const proof = await this.submitAndAwaitProof(
@@ -9897,12 +9877,11 @@ var SphereTokenEngine = class {
         import_TokenSalt.TokenSalt.fromBytes(deriveRealization(this.privateKeyHex, transferId, i, "salt"))
       )
     );
-    const split = await import_TokenSplit.TokenSplit.split(
-      params.token.sdkToken,
-      decodeSpherePaymentData,
-      requests,
-      import_StateMask.StateMask.fromBytes(deriveRealization(this.privateKeyHex, transferId, this.resolveOpIndex(options), "burn"))
-    );
+    const split = await import_TokenSplit.TokenSplit.split(params.token.sdkToken, decodeSpherePaymentData, requests, {
+      burnStateMask: import_StateMask.StateMask.fromBytes(
+        deriveRealization(this.privateKeyHex, transferId, this.resolveOpIndex(options), "burn")
+      )
+    });
     const burntToken = await this.resolveBurntToken({ params, split, transferId, options });
     const settled = [];
     for (let start = 0; start < split.tokens.length; start += MAX_MINT_CONCURRENCY) {
@@ -9982,9 +9961,14 @@ var SphereTokenEngine = class {
     await Promise.all(
       ctx.split.tokens.map(async (leg) => {
         const data = await leg.paymentData.encode();
-        const probe = await import_MintTransaction.MintTransaction.create(leg.networkId, leg.recipient, data, leg.tokenType, leg.salt, null);
+        const probe = await import_MintTransaction.MintTransaction.create(leg.networkId, leg.recipient, {
+          data,
+          tokenType: leg.tokenType,
+          salt: leg.salt,
+          justification: null
+        });
         const response = await this.deps.client.getInclusionProof(await import_StateId.StateId.fromTransaction(probe));
-        if (response.inclusionProof.certificationData !== null) {
+        if (response.inclusionProof !== null) {
           throw new SplitCheckpointLostError(
             "a split mint leaf is certified on-chain but no burn checkpoint exists \u2014 outputs are unrecoverable"
           );
@@ -9996,14 +9980,12 @@ var SphereTokenEngine = class {
   async mintSplitOutput(splitToken, burntToken, options) {
     const data = await splitToken.paymentData.encode();
     const justification = import_SplitMintJustification.SplitMintJustification.create(burntToken, splitToken.proofs).toCBOR();
-    const mintTx = await import_MintTransaction.MintTransaction.create(
-      splitToken.networkId,
-      splitToken.recipient,
+    const mintTx = await import_MintTransaction.MintTransaction.create(splitToken.networkId, splitToken.recipient, {
       data,
-      splitToken.tokenType,
-      splitToken.salt,
+      tokenType: splitToken.tokenType,
+      salt: splitToken.salt,
       justification
-    );
+    });
     const certData = await import_CertificationData.CertificationData.fromMintTransaction(mintTx);
     const proof = await this.submitSplitMintLeg(certData, mintTx, options);
     const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
@@ -10048,7 +10030,7 @@ var SphereTokenEngine = class {
     );
     const stateId = await import_StateId.StateId.fromTransaction(probe);
     const response = await this.deps.client.getInclusionProof(stateId);
-    return response.inclusionProof.certificationData !== null;
+    return response.inclusionProof !== null;
   }
   // ── serialization ────────────────────────────────────────────────────────────
   /** @inheritDoc — SDK-derived (Token.fromCBOR → latestTransaction.calculateStateHash().imprint). */
@@ -10132,7 +10114,13 @@ var SphereTokenEngine = class {
     let submitRejectedCleanly = false;
     try {
       const { value: response, retried } = await retryTransient(
-        () => this.deps.client.submitCertificationRequest(certificationData),
+        async () => {
+          const answer = await this.deps.client.submitCertificationRequest(certificationData);
+          if (String(answer.status) === String(import_CertificationResponse.CertificationStatus.SERVICE_NOT_READY)) {
+            throw new TransientSubmitAnswer(String(answer.status));
+          }
+          return answer;
+        },
         signal,
         this.deps.proofPollIntervalMs ?? DEFAULT_PROOF_POLL_INTERVAL_MS
       );
@@ -10187,8 +10175,6 @@ var SphereTokenEngine = class {
       }
     }
     const blob = {
-      v: TOKEN_BLOB_VERSION,
-      network: sdkToken.genesis.networkId.id,
       tokenId: import_HexConverter.HexConverter.encode(sdkToken.id.bytes),
       token: sdkToken.toCBOR()
     };
@@ -11332,8 +11318,19 @@ function coalesced(run, observe) {
 }
 
 // modules/payments-v2/stores.ts
+var KV_PREFIX = "pv2g2:";
+var SUPERSEDED_KV_PREFIXES = ["pv2:"];
+async function sweepSupersededState(storage) {
+  for (const prefix of SUPERSEDED_KV_PREFIXES) {
+    try {
+      await storage.clear(prefix);
+    } catch (err) {
+      logger.warn("PaymentsV2", `could not clear superseded state under "${prefix}": ${String(err)}`);
+    }
+  }
+}
 function createScopedKV(storage, network, chainPubkey) {
-  const prefix = `pv2:${network}:${chainPubkey}:`;
+  const prefix = `${KV_PREFIX}${network}:${chainPubkey}:`;
   return {
     async get(key) {
       const raw = await storage.get(prefix + key);
@@ -11915,12 +11912,7 @@ var TransferMachine = class {
     let total = 0n;
     for (const outcome of committed) {
       if (outcome.recipientBlob === void 0) continue;
-      const token = await engine.decodeToken({
-        v: TOKEN_BLOB_VERSION,
-        network: 0,
-        tokenId: "",
-        token: outcome.recipientBlob
-      });
+      const token = await engine.decodeToken({ tokenId: "", token: outcome.recipientBlob });
       total += engine.balanceOf(token, coinId);
     }
     return total.toString();
@@ -12036,8 +12028,9 @@ async function fetchSources(deps, jobs) {
   const engine = deps.engine();
   for (const [tokenId, bytes] of blobs) {
     try {
-      decoded.set(tokenId, await engine.decodeToken({ v: TOKEN_BLOB_VERSION, network: 0, tokenId, token: bytes }));
-    } catch {
+      decoded.set(tokenId, await engine.decodeToken({ tokenId, token: bytes }));
+    } catch (err) {
+      logger.warn("PaymentsV2", `resume: source ${tokenId} did not decode \u2014 ${String(err)}`);
     }
   }
   return decoded;
@@ -13064,22 +13057,24 @@ var Receive = class {
    * the tokens just accepted, and the balance would still only move at the end.
    * Ordering is preserved: store() still precedes the ack (§5.7).
    */
-  async maybeRefresh(deps, pending, epochOf) {
+  async maybeRefresh(ctx) {
+    const { deps, pending, pageEpoch } = ctx;
     if (deps.refreshView === void 0) return;
     const now = deps.now?.() ?? Date.now();
     if (now - this.lastRefreshAt < REFRESH_INTERVAL_MS) return;
     this.lastRefreshAt = now;
-    await flushAcks(deps, pending, epochOf);
-    deps.refreshView();
+    if ((await flushAcks(deps, pending, pageEpoch)).progressed) deps.refreshView();
   }
   /** One listing pass: process each entry, flushing and refreshing as it goes. */
   async drainPages(ctx, basis) {
-    const { deps, engine, pending, stored, pageEpoch } = ctx;
+    const { deps, pending, pageEpoch, claimable } = ctx;
     for await (const entry of deps.delivery.incoming(basis === null ? void 0 : String(basis.cursor))) {
-      const storedBefore = stored.length;
-      await this.processEntry(deps, engine, entry, pending, stored);
-      if (pending.length >= ACK_BATCH_SIZE) await flushAcks(deps, pending, pageEpoch);
-      if (stored.length > storedBefore) await this.maybeRefresh(deps, pending, pageEpoch);
+      const claimableBefore = claimable.n;
+      await this.processEntry(ctx, entry);
+      if (pending.length >= ACK_BATCH_SIZE) {
+        if (!(await flushAcks(deps, pending, pageEpoch)).progressed) return;
+      }
+      if (claimable.n > claimableBefore) await this.maybeRefresh(ctx);
     }
     await flushAcks(deps, pending, pageEpoch);
   }
@@ -13090,11 +13085,16 @@ var Receive = class {
     const stored = [];
     const pending = [];
     const pageEpoch = () => deps.delivery.incomingEpoch() ?? deps.syncEpoch();
+    const claimable = { n: 0 };
+    const finish = () => {
+      if (claimable.n > 0) deps.refreshView?.();
+      return stored;
+    };
     try {
       const record = await deps.kv.get(STORE_KEYS.streamCursor("mailbox"));
       let basis = record !== null && record.syncEpoch === deps.syncEpoch() ? record : null;
       for (let pass = 0; pass < 2; pass++) {
-        await this.drainPages({ deps, engine, pending, stored, pageEpoch }, basis);
+        await this.drainPages({ deps, engine, pending, stored, pageEpoch, claimable }, basis);
         const served = deps.delivery.incomingEpoch();
         if (basis === null || served === null || served === basis.syncEpoch) break;
         await deps.kv.remove(STORE_KEYS.streamCursor("mailbox"));
@@ -13102,22 +13102,25 @@ var Receive = class {
       }
     } catch (err) {
       logger.warn("PaymentsV2", "receive drain interrupted \u2014 unacked entries retry next drain:", err);
-      if (isRetryableAckError(err)) return stored;
+      if (isRetryableAckError(err)) return finish();
       await flushAcks(deps, pending, pageEpoch).catch((flushErr) => {
         logger.warn("PaymentsV2", "receive ack flush failed \u2014 cursor holds at the acked prefix:", flushErr);
+        return { progressed: false };
       });
     }
-    if (stored.length > 0) deps.refreshView?.();
-    return stored;
+    return finish();
   }
-  async processEntry(deps, engine, entry, pending, stored) {
+  async processEntry(ctx, entry) {
+    const { deps, engine, pending, stored, claimable } = ctx;
     const screened = await screen(deps, engine, entry);
     if (screened.kind === "ack") {
       pending.push(screened.ack);
+      if (screened.ack.disposition === "claimed") claimable.n += 1;
       return;
     }
     await deps.view.store(screened.record);
     pending.push(claimAck(entry));
+    claimable.n += 1;
     const transfer = await announce(deps, entry, screened.record);
     stored.push(transfer);
     deps.emit("transfer:incoming", transfer);
@@ -13127,13 +13130,9 @@ async function screen(deps, engine, entry) {
   const blobBytes = await entry.fetchBlob();
   let token;
   try {
-    token = await engine.decodeToken({
-      v: TOKEN_BLOB_VERSION,
-      network: 0,
-      tokenId: "",
-      token: blobBytes
-    });
-  } catch {
+    token = await engine.decodeToken({ tokenId: "", token: blobBytes });
+  } catch (err) {
+    logger.warn("PaymentsV2", `receive: undecodable blob rejected \u2014 ${String(err)}`);
     return { kind: "ack", ack: rejectAck(entry, "invalid") };
   }
   const verdict = await engine.verify(token);
@@ -13178,7 +13177,8 @@ async function announce(deps, entry, record) {
   };
 }
 async function flushAcks(deps, pending, epochOf) {
-  if (pending.length === 0) return;
+  if (pending.length === 0) return { progressed: true };
+  const before = pending.length;
   let lastAcked = null;
   try {
     const settled = await settleAcks(deps, pending);
@@ -13196,6 +13196,7 @@ async function flushAcks(deps, pending, epochOf) {
       await deps.kv.set(STORE_KEYS.streamCursor("mailbox"), record);
     }
   }
+  return { progressed: pending.length < before };
 }
 async function settleAcks(deps, pending) {
   const batch = deps.delivery.ackBatch?.bind(deps.delivery);
@@ -14534,7 +14535,7 @@ var PaymentsFacade = class {
       if (bytes === void 0) {
         throw new SphereError(`Selected source ${tokenId} has no blob in storage`, "STORAGE_ERROR");
       }
-      const token = await engine.decodeToken({ v: TOKEN_BLOB_VERSION, network: 0, tokenId, token: bytes });
+      const token = await engine.decodeToken({ tokenId, token: bytes });
       const keys = await engine.deliveryKeys(bytes);
       spentStates[tokenId] = { local: keys.stateHash, protocol: keys.stateHash };
       sources.set(tokenId, token);
@@ -15716,7 +15717,9 @@ var WalletApiDeliveryPort = class {
       await this.settleClaims(acks, settled, outcomes);
       await this.settleRejects(acks, settled);
     } catch (err) {
-      await this.addSeenAll(settled).catch(() => void 0);
+      await this.addSeenAll(settled).catch((seenErr) => {
+        logger.warn("WalletApiDelivery", `seen-set write failed for ${String(settled.length)} committed acks:`, seenErr);
+      });
       throw asRetryable(err);
     }
     await this.addSeenAll(settled);
@@ -15979,6 +15982,7 @@ function composePaymentsV2(spec) {
   const network = spec.composition.network;
   const identitySlice = { privateKey: identity.privateKey, chainPubkey: identity.chainPubkey };
   const kv = createScopedKV(host.storage, network, identity.chainPubkey);
+  void sweepSupersededState(host.storage);
   const fieldKey = deriveFieldEncryptionKey(identity.privateKey);
   const transport = spec.composition.factory({
     identity: identitySlice,
@@ -16270,11 +16274,10 @@ var Sphere = class _Sphere {
     return config;
   }
   /**
-   * The ONE sanctioned refusal fossil of the P11 flip (revisit-and-delete after
-   * one release): `accounting`/`swap` were public init flags — silently
-   * ignoring them would hide that invoices/swaps no longer exist in the SDK.
-   * `paymentsV2: true` stays an accepted no-op for the same one release (the
-   * live frontend passes it today).
+   * The ONE sanctioned refusal fossil of the P11 flip: `accounting`/`swap` were
+   * public init flags — silently ignoring them would hide that invoices/swaps no
+   * longer exist in the SDK. Kept through 0.15.0, where consumers re-integrate
+   * across the wire break and a silent no-op would be worst.
    */
   static refuseRetiredModuleOptions(options) {
     if (options.accounting) {
@@ -16541,7 +16544,7 @@ var Sphere = class _Sphere {
   }
   /**
    * Clear all SDK-owned wallet data from storage: wallet keys, per-address
-   * data, and the payments vertical's `pv2:{network}:{pubkey}:*` scoped KV
+   * data, and the payments vertical's `pv2g2:{network}:{pubkey}:*` scoped KV
    * (refresh token, cursors, journals — all live in the plain StorageProvider,
    * so the full KV wipe below removes them). Tokens are server-custody; the
    * only local token artifacts are orphaned `sphere-token-storage-*` IndexedDB
@@ -16651,10 +16654,6 @@ var Sphere = class _Sphere {
     }
     return facade;
   }
-  /** @deprecated Alias of {@link payments} kept for one release (the live frontend calls it). Null when no vertical runs. */
-  get paymentsV2() {
-    return this._paymentsV2Active?.facade ?? null;
-  }
   /** Communications module */
   get communications() {
     this.ensureReady();