@unicitylabs/sphere-sdk 0.16.0 → 0.17.0

package/dist/token-engine/index.cjs

@@ -78,6 +78,8 @@ var import_DataHasherFactory = require("@unicitylabs/state-transition-sdk/lib/cr
 var import_CborSerializer = require("@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborSerializer.js");
 var import_CborDeserializer = require("@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborDeserializer.js");
 var import_CborError = require("@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborError.js");
+var import_CborReader = require("@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborReader.js");
+var import_MajorType = require("@unicitylabs/state-transition-sdk/lib/serialization/cbor/MajorType.js");
 var import_Asset = require("@unicitylabs/state-transition-sdk/lib/payment/asset/Asset.js");
 var import_AssetId = require("@unicitylabs/state-transition-sdk/lib/payment/asset/AssetId.js");
 var import_PaymentAssetCollection = require("@unicitylabs/state-transition-sdk/lib/payment/asset/PaymentAssetCollection.js");
@@ -1035,6 +1037,123 @@ async function burntTokenFromCheckpoint(deps, storedBytes, reDerivedBurnTx, sour
   return burntToken;
 }
 
+// token-engine/value-envelope.ts
+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 import_CborReader.CborReader(bytes).readLength(import_MajorType.MajorType.TAG);
+  } catch {
+    return null;
+  }
+}
+function isAssetShaped(item) {
+  try {
+    return import_CborDeserializer.CborDeserializer.decodeArray(item, 2).every(
+      (field) => majorTypeOf(field) === import_MajorType.MajorType.BYTE_STRING
+    );
+  } catch {
+    return false;
+  }
+}
+function arrayItemsOrNull(bytes) {
+  try {
+    return import_CborDeserializer.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 import_CborDeserializer.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 === import_MajorType.MajorType.TAG) {
+    const inner = headTagNumber(body);
+    return inner === SpherePaymentData.CBOR_TAG || inner === SELF_DESCRIBED_CBOR_TAG;
+  }
+  if (major === import_MajorType.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 === import_MajorType.MajorType.TAG) return classifyTagged(genesisData);
+  if (major === import_MajorType.MajorType.ARRAY) return classifyArray(genesisData);
+  return { envelope: "none_other", value: null };
+}
+function wrapToken(sdkToken) {
+  const { envelope, value } = classifyValueEnvelope(sdkToken.genesis.data);
+  const blob = {
+    tokenId: import_HexConverter.HexConverter.encode(sdkToken.id.bytes),
+    token: sdkToken.toCBOR()
+  };
+  return {
+    sdkToken,
+    blob,
+    value,
+    valueEnvelope: envelope,
+    tokenType: import_HexConverter.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;
@@ -1091,7 +1210,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;
@@ -1121,9 +1240,10 @@ var SphereTokenEngine = class {
     );
     const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
     const token = await import_Token.Token.mint(certified, this.deps.verificationContext);
-    return this.wrapToken(token);
+    return wrapToken(token);
   }
   async mintDataToken(params, options) {
+    assertMintableData(params.data);
     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();
@@ -1138,7 +1258,7 @@ var SphereTokenEngine = class {
     );
     const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
     const token = await import_Token.Token.mint(certified, this.deps.verificationContext);
-    return this.wrapToken(token);
+    return wrapToken(token);
   }
   async transfer(params, options) {
     this.assertOwned(params.token);
@@ -1161,13 +1281,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) => import_SplitTokenRequest.SplitTokenRequest.create(
@@ -1289,7 +1415,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 import_Token.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
@@ -1347,7 +1473,7 @@ var SphereTokenEngine = class {
         "VALIDATION_ERROR"
       );
     }
-    return this.wrapToken(sdkToken);
+    return wrapToken(sdkToken);
   }
   // ── internals ────────────────────────────────────────────────────────────────
   /**
@@ -1459,34 +1585,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: import_HexConverter.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 import_CborDeserializer.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.