@unicitylabs/sphere-sdk 0.14.11 → 0.15.0

package/dist/index.d.cts

@@ -1964,7 +1964,7 @@ declare const STORAGE_KEYS_GLOBAL: {
  * Example: sphere_DIRECT_abc123_xyz789_pending_transfers
  *
  * Note: Token data is server custody (wallet-api backend), not here; the
- * payments vertical's durable client state self-prefixes `pv2:{network}:{pubkey}:`.
+ * payments vertical's durable client state self-prefixes `pv2g2:{network}:{pubkey}:`.
  */
 declare const STORAGE_KEYS_ADDRESS: {
     /** Transfer outbox for this address (pre-flip key name; kept as the network-scoping witness) */
@@ -2743,8 +2743,6 @@ type InitProgressCallback = (progress: InitProgress) => void;
 interface SphereWalletApiOptions {
     /** Wallet-api transport config — REQUIRED (init throws INVALID_CONFIG without it). */
     walletApi?: WalletApiTransportConfig;
-    /** @deprecated The payments-v2 vertical is the only path since the P11 flip — accepted as a no-op for one release. */
-    paymentsV2?: boolean;
     /** @deprecated REMOVED with the P11 flip — any truthy value throws INVALID_CONFIG (invoicing no longer exists in the SDK). */
     accounting?: unknown;
     /** @deprecated REMOVED with the P11 flip — any truthy value throws INVALID_CONFIG (swaps no longer exist in the SDK). */
@@ -3076,11 +3074,10 @@ declare class Sphere {
      */
     private static resolveMarketConfig;
     /**
-     * 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.
      */
     private static refuseRetiredModuleOptions;
     /**
@@ -3107,7 +3104,7 @@ declare class Sphere {
     static import(options: SphereImportOptions): Promise<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
@@ -3153,8 +3150,6 @@ declare class Sphere {
     static generateMnemonic(strength?: 128 | 256): string;
     /** Payments (the §4 facade — the active address's running vertical). */
     get payments(): PaymentsV2;
-    /** @deprecated Alias of {@link payments} kept for one release (the live frontend calls it). Null when no vertical runs. */
-    get paymentsV2(): PaymentsV2 | null;
     /** Communications module */
     get communications(): CommunicationsModule;
     /** Group chat module (NIP-29). Null if not configured. */

package/dist/index.d.ts

@@ -1964,7 +1964,7 @@ declare const STORAGE_KEYS_GLOBAL: {
  * Example: sphere_DIRECT_abc123_xyz789_pending_transfers
  *
  * Note: Token data is server custody (wallet-api backend), not here; the
- * payments vertical's durable client state self-prefixes `pv2:{network}:{pubkey}:`.
+ * payments vertical's durable client state self-prefixes `pv2g2:{network}:{pubkey}:`.
  */
 declare const STORAGE_KEYS_ADDRESS: {
     /** Transfer outbox for this address (pre-flip key name; kept as the network-scoping witness) */
@@ -2743,8 +2743,6 @@ type InitProgressCallback = (progress: InitProgress) => void;
 interface SphereWalletApiOptions {
     /** Wallet-api transport config — REQUIRED (init throws INVALID_CONFIG without it). */
     walletApi?: WalletApiTransportConfig;
-    /** @deprecated The payments-v2 vertical is the only path since the P11 flip — accepted as a no-op for one release. */
-    paymentsV2?: boolean;
     /** @deprecated REMOVED with the P11 flip — any truthy value throws INVALID_CONFIG (invoicing no longer exists in the SDK). */
     accounting?: unknown;
     /** @deprecated REMOVED with the P11 flip — any truthy value throws INVALID_CONFIG (swaps no longer exist in the SDK). */
@@ -3076,11 +3074,10 @@ declare class Sphere {
      */
     private static resolveMarketConfig;
     /**
-     * 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.
      */
     private static refuseRetiredModuleOptions;
     /**
@@ -3107,7 +3104,7 @@ declare class Sphere {
     static import(options: SphereImportOptions): Promise<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
@@ -3153,8 +3150,6 @@ declare class Sphere {
     static generateMnemonic(strength?: 128 | 256): string;
     /** Payments (the §4 facade — the active address's running vertical). */
     get payments(): PaymentsV2;
-    /** @deprecated Alias of {@link payments} kept for one release (the live frontend calls it). Null when no vertical runs. */
-    get paymentsV2(): PaymentsV2 | null;
     /** Communications module */
     get communications(): CommunicationsModule;
     /** Group chat module (NIP-29). Null if not configured. */

package/dist/index.js

@@ -9401,7 +9401,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 JsonRpcNetworkError && TRANSIENT_HTTP_STATUSES.has(err.status);
 }
 function pause(ms, signal) {
@@ -9522,37 +9530,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 = CborDeserializer.decodeTag(bytes);
-  if (tag.tag !== TOKEN_BLOB_TAG) {
-    throw new CborError(`Invalid TokenBlob tag: ${tag.tag}`);
-  }
-  const fields = CborDeserializer.decodeArray(tag.data, 4);
-  const v = Number(CborDeserializer.decodeUnsignedInteger(fields[0]));
-  if (v !== TOKEN_BLOB_VERSION) {
-    throw new CborError(`Unsupported TokenBlob version: ${v}`);
-  }
-  return {
-    v,
-    network: Number(CborDeserializer.decodeUnsignedInteger(fields[1])),
-    tokenId: CborDeserializer.decodeTextString(fields[2]),
-    token: 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 Token.fromCBOR(unwrapTokenBlobBytes(blobBytes));
+  const token = await Token.fromCBOR(blobBytes);
   const stateHash = HexConverter.encode((await token.latestTransaction.calculateStateHash()).imprint);
   return { tokenId: HexConverter.encode(token.id.bytes), stateHash };
 }
@@ -9606,8 +9586,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++) {
@@ -9757,13 +9737,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 MintTransaction.create(
-      this.deps.networkId,
-      recipient,
+    const mintTx = await MintTransaction.create(this.deps.networkId, recipient, {
       data,
-      new TokenType(deriveRealization(this.privateKeyHex, transferId, opIndex, "tokenType")),
-      TokenSalt.fromBytes(deriveRealization(this.privateKeyHex, transferId, opIndex, "mint"))
-    );
+      tokenType: new TokenType(deriveRealization(this.privateKeyHex, transferId, opIndex, "tokenType")),
+      salt: TokenSalt.fromBytes(deriveRealization(this.privateKeyHex, transferId, opIndex, "mint"))
+    });
     const certificationData = await CertificationData.fromMintTransaction(mintTx);
     const proof = await this.submitAndAwaitProof(
       certificationData,
@@ -9780,7 +9758,7 @@ var SphereTokenEngine = class {
     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();
-    const mintTx = await MintTransaction.create(this.deps.networkId, recipient, params.data, tokenType, salt);
+    const mintTx = await MintTransaction.create(this.deps.networkId, recipient, { data: params.data, tokenType, salt });
     const certificationData = await CertificationData.fromMintTransaction(mintTx);
     const proof = await this.submitAndAwaitProof(
       certificationData,
@@ -9800,7 +9778,9 @@ var SphereTokenEngine = class {
     const stateMask = StateMask.fromBytes(
       deriveRealization(this.privateKeyHex, transferId, this.resolveOpIndex(options), "stateMask")
     );
-    const transferTx = await TransferTransaction.create(params.token.sdkToken, recipient, stateMask, params.data ?? null);
+    const transferTx = await TransferTransaction.create(params.token.sdkToken, recipient, stateMask, {
+      data: params.data ?? null
+    });
     const unlockScript = await SignaturePredicateUnlockScript.create(transferTx, this.deps.signingService);
     const certificationData = await CertificationData.fromTransaction(transferTx, unlockScript);
     const proof = await this.submitAndAwaitProof(
@@ -9827,12 +9807,11 @@ var SphereTokenEngine = class {
         TokenSalt.fromBytes(deriveRealization(this.privateKeyHex, transferId, i, "salt"))
       )
     );
-    const split = await TokenSplit.split(
-      params.token.sdkToken,
-      decodeSpherePaymentData,
-      requests,
-      StateMask.fromBytes(deriveRealization(this.privateKeyHex, transferId, this.resolveOpIndex(options), "burn"))
-    );
+    const split = await TokenSplit.split(params.token.sdkToken, decodeSpherePaymentData, requests, {
+      burnStateMask: 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) {
@@ -9912,9 +9891,14 @@ var SphereTokenEngine = class {
     await Promise.all(
       ctx.split.tokens.map(async (leg) => {
         const data = await leg.paymentData.encode();
-        const probe = await MintTransaction.create(leg.networkId, leg.recipient, data, leg.tokenType, leg.salt, null);
+        const probe = await MintTransaction.create(leg.networkId, leg.recipient, {
+          data,
+          tokenType: leg.tokenType,
+          salt: leg.salt,
+          justification: null
+        });
         const response = await this.deps.client.getInclusionProof(await 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"
           );
@@ -9926,14 +9910,12 @@ var SphereTokenEngine = class {
   async mintSplitOutput(splitToken, burntToken, options) {
     const data = await splitToken.paymentData.encode();
     const justification = SplitMintJustification.create(burntToken, splitToken.proofs).toCBOR();
-    const mintTx = await MintTransaction.create(
-      splitToken.networkId,
-      splitToken.recipient,
+    const mintTx = await MintTransaction.create(splitToken.networkId, splitToken.recipient, {
       data,
-      splitToken.tokenType,
-      splitToken.salt,
+      tokenType: splitToken.tokenType,
+      salt: splitToken.salt,
       justification
-    );
+    });
     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, this.deps.unicityCertificateVerifier, proof);
@@ -9978,7 +9960,7 @@ var SphereTokenEngine = class {
     );
     const stateId = await 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). */
@@ -10062,7 +10044,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(CertificationStatus.SERVICE_NOT_READY)) {
+            throw new TransientSubmitAnswer(String(answer.status));
+          }
+          return answer;
+        },
         signal,
         this.deps.proofPollIntervalMs ?? DEFAULT_PROOF_POLL_INTERVAL_MS
       );
@@ -10117,8 +10105,6 @@ var SphereTokenEngine = class {
       }
     }
     const blob = {
-      v: TOKEN_BLOB_VERSION,
-      network: sdkToken.genesis.networkId.id,
       tokenId: HexConverter.encode(sdkToken.id.bytes),
       token: sdkToken.toCBOR()
     };
@@ -11262,8 +11248,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);
@@ -11845,12 +11842,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();
@@ -11966,8 +11958,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;
@@ -13067,13 +13060,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);
@@ -14476,7 +14465,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);
@@ -15923,6 +15912,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,
@@ -16214,11 +16204,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) {
@@ -16485,7 +16474,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
@@ -16595,10 +16584,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();