@unicitylabs/sphere-sdk 0.16.0 → 0.17.0

package/dist/token-engine/index.d.cts

@@ -3,6 +3,9 @@ import { IPaymentData } from '@unicitylabs/state-transition-sdk/lib/payment/IPay
 import { Asset } from '@unicitylabs/state-transition-sdk/lib/payment/asset/Asset.js';
 import { PaymentAssetCollection } from '@unicitylabs/state-transition-sdk/lib/payment/asset/PaymentAssetCollection.js';
 
+/** `none_*` = coinless; `bare_collection` = a dialect this SDK cannot read. */
+type ValueEnvelope = 'sphere' | 'bare_collection' | 'none_tag' | 'none_other' | 'none_absent';
+
 /**
  * token-engine/types.ts — the FROZEN, sphere-domain contract surface.
  *
@@ -65,6 +68,22 @@ interface SphereToken {
     readonly blob: TokenBlob;
     /** Decoded value (cached); null when the token carries no sphere payment data. */
     readonly value: SphereValue | null;
+    /**
+     * Which value envelope the genesis payload carried (#778). Distinguishes the
+     * reasons `value` is null, which the old boolean predicate collapsed:
+     * `'none_*'` means the token genuinely names no coin — a COINLESS token — while
+     * `'bare_collection'` means it carries coins in the bridged dialect this SDK
+     * does not decode, so a zero here is "cannot read", not "has none". A corrupt
+     * envelope never reaches this field: it throws during classification.
+     */
+    readonly valueEnvelope: ValueEnvelope;
+    /**
+     * Genesis `TokenType`, lowercase hex. The token's CLASS, never its instance —
+     * `blob.tokenId` is the instance key (wallet-api#147). Only as meaningful as its
+     * minter made it: `mint()` and split outputs derive one per operation, so for
+     * value tokens it is per-mint noise. Never a spend gate.
+     */
+    readonly tokenType: string;
 }
 interface MintParams {
     /** Recipient's 33-byte compressed chain pubkey; engine derives the predicate. */

package/dist/token-engine/index.d.ts

@@ -3,6 +3,9 @@ import { IPaymentData } from '@unicitylabs/state-transition-sdk/lib/payment/IPay
 import { Asset } from '@unicitylabs/state-transition-sdk/lib/payment/asset/Asset.js';
 import { PaymentAssetCollection } from '@unicitylabs/state-transition-sdk/lib/payment/asset/PaymentAssetCollection.js';
 
+/** `none_*` = coinless; `bare_collection` = a dialect this SDK cannot read. */
+type ValueEnvelope = 'sphere' | 'bare_collection' | 'none_tag' | 'none_other' | 'none_absent';
+
 /**
  * token-engine/types.ts — the FROZEN, sphere-domain contract surface.
  *
@@ -65,6 +68,22 @@ interface SphereToken {
     readonly blob: TokenBlob;
     /** Decoded value (cached); null when the token carries no sphere payment data. */
     readonly value: SphereValue | null;
+    /**
+     * Which value envelope the genesis payload carried (#778). Distinguishes the
+     * reasons `value` is null, which the old boolean predicate collapsed:
+     * `'none_*'` means the token genuinely names no coin — a COINLESS token — while
+     * `'bare_collection'` means it carries coins in the bridged dialect this SDK
+     * does not decode, so a zero here is "cannot read", not "has none". A corrupt
+     * envelope never reaches this field: it throws during classification.
+     */
+    readonly valueEnvelope: ValueEnvelope;
+    /**
+     * Genesis `TokenType`, lowercase hex. The token's CLASS, never its instance —
+     * `blob.tokenId` is the instance key (wallet-api#147). Only as meaningful as its
+     * minter made it: `mint()` and split outputs derive one per operation, so for
+     * value tokens it is per-mint noise. Never a spend gate.
+     */
+    readonly tokenType: string;
 }
 interface MintParams {
     /** Recipient's 33-byte compressed chain pubkey; engine derives the predicate. */

package/dist/token-engine/index.js

@@ -43,6 +43,8 @@ import { DataHasherFactory } from "@unicitylabs/state-transition-sdk/lib/crypto/
 import { CborSerializer } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborSerializer.js";
 import { CborDeserializer } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborDeserializer.js";
 import { CborError } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborError.js";
+import { CborReader } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborReader.js";
+import { MajorType } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/MajorType.js";
 import { Asset } from "@unicitylabs/state-transition-sdk/lib/payment/asset/Asset.js";
 import { AssetId } from "@unicitylabs/state-transition-sdk/lib/payment/asset/AssetId.js";
 import { PaymentAssetCollection } from "@unicitylabs/state-transition-sdk/lib/payment/asset/PaymentAssetCollection.js";
@@ -1000,6 +1002,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 CborReader(bytes).readLength(MajorType.TAG);
+  } catch {
+    return null;
+  }
+}
+function isAssetShaped(item) {
+  try {
+    return CborDeserializer.decodeArray(item, 2).every(
+      (field) => majorTypeOf(field) === MajorType.BYTE_STRING
+    );
+  } catch {
+    return false;
+  }
+}
+function arrayItemsOrNull(bytes) {
+  try {
+    return 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 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 === MajorType.TAG) {
+    const inner = headTagNumber(body);
+    return inner === SpherePaymentData.CBOR_TAG || inner === SELF_DESCRIBED_CBOR_TAG;
+  }
+  if (major === 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 === MajorType.TAG) return classifyTagged(genesisData);
+  if (major === MajorType.ARRAY) return classifyArray(genesisData);
+  return { envelope: "none_other", value: null };
+}
+function wrapToken(sdkToken) {
+  const { envelope, value } = classifyValueEnvelope(sdkToken.genesis.data);
+  const blob = {
+    tokenId: HexConverter.encode(sdkToken.id.bytes),
+    token: sdkToken.toCBOR()
+  };
+  return {
+    sdkToken,
+    blob,
+    value,
+    valueEnvelope: envelope,
+    tokenType: 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;
@@ -1056,7 +1175,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;
@@ -1086,9 +1205,10 @@ var SphereTokenEngine = class {
     );
     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);
+    return wrapToken(token);
   }
   async mintDataToken(params, options) {
+    assertMintableData(params.data);
     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();
@@ -1103,7 +1223,7 @@ var SphereTokenEngine = class {
     );
     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);
+    return wrapToken(token);
   }
   async transfer(params, options) {
     this.assertOwned(params.token);
@@ -1126,13 +1246,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) => SplitTokenRequest.create(
@@ -1254,7 +1380,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 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
@@ -1312,7 +1438,7 @@ var SphereTokenEngine = class {
         "VALIDATION_ERROR"
       );
     }
-    return this.wrapToken(sdkToken);
+    return wrapToken(sdkToken);
   }
   // ── internals ────────────────────────────────────────────────────────────────
   /**
@@ -1424,34 +1550,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: 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 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.