@unicitylabs/sphere-sdk 0.9.0-dev.0 → 0.9.0-dev.1

package/dist/token-engine/index.js

@@ -0,0 +1,647 @@
+// token-engine/sdk.ts
+import { StateTransitionClient } from "@unicitylabs/state-transition-sdk/lib/StateTransitionClient.js";
+import { AggregatorClient } from "@unicitylabs/state-transition-sdk/lib/api/AggregatorClient.js";
+import { NetworkId } from "@unicitylabs/state-transition-sdk/lib/api/NetworkId.js";
+import { CertificationData } from "@unicitylabs/state-transition-sdk/lib/api/CertificationData.js";
+import { CertificationResponse, CertificationStatus } from "@unicitylabs/state-transition-sdk/lib/api/CertificationResponse.js";
+import { StateId } from "@unicitylabs/state-transition-sdk/lib/api/StateId.js";
+import { InclusionProof } from "@unicitylabs/state-transition-sdk/lib/api/InclusionProof.js";
+import { InclusionProofResponse } from "@unicitylabs/state-transition-sdk/lib/api/InclusionProofResponse.js";
+import { RootTrustBase } from "@unicitylabs/state-transition-sdk/lib/api/bft/RootTrustBase.js";
+import { waitInclusionProof } from "@unicitylabs/state-transition-sdk/lib/util/InclusionProofUtils.js";
+import { Token } from "@unicitylabs/state-transition-sdk/lib/transaction/Token.js";
+import { MintTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/MintTransaction.js";
+import { TransferTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/TransferTransaction.js";
+import { CertifiedMintTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/CertifiedMintTransaction.js";
+import { CertifiedTransferTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/CertifiedTransferTransaction.js";
+import { TokenId } from "@unicitylabs/state-transition-sdk/lib/transaction/TokenId.js";
+import { TokenType } from "@unicitylabs/state-transition-sdk/lib/transaction/TokenType.js";
+import { TokenSalt } from "@unicitylabs/state-transition-sdk/lib/transaction/TokenSalt.js";
+import { MintJustificationVerifierService } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/MintJustificationVerifierService.js";
+import { EncodedPredicate } from "@unicitylabs/state-transition-sdk/lib/predicate/EncodedPredicate.js";
+import { SignaturePredicate } from "@unicitylabs/state-transition-sdk/lib/predicate/builtin/SignaturePredicate.js";
+import { SignaturePredicateUnlockScript } from "@unicitylabs/state-transition-sdk/lib/predicate/builtin/SignaturePredicateUnlockScript.js";
+import { BurnPredicate } from "@unicitylabs/state-transition-sdk/lib/predicate/builtin/BurnPredicate.js";
+import { PredicateVerifierService } from "@unicitylabs/state-transition-sdk/lib/predicate/verification/PredicateVerifierService.js";
+import { SigningService } from "@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/SigningService.js";
+import { Signature } from "@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/Signature.js";
+import { MintSigningService } from "@unicitylabs/state-transition-sdk/lib/crypto/MintSigningService.js";
+import { HashAlgorithm } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/HashAlgorithm.js";
+import { DataHash } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHash.js";
+import { DataHasher } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHasher.js";
+import { DataHasherFactory } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHasherFactory.js";
+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 { 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";
+import { TokenSplit } from "@unicitylabs/state-transition-sdk/lib/payment/TokenSplit.js";
+import { SplitTokenRequest } from "@unicitylabs/state-transition-sdk/lib/payment/SplitTokenRequest.js";
+import { SplitToken } from "@unicitylabs/state-transition-sdk/lib/payment/SplitToken.js";
+import { SplitAssetProof } from "@unicitylabs/state-transition-sdk/lib/payment/SplitAssetProof.js";
+import { SplitMintJustification } from "@unicitylabs/state-transition-sdk/lib/payment/SplitMintJustification.js";
+import { SplitMintJustificationVerifier } from "@unicitylabs/state-transition-sdk/lib/payment/SplitMintJustificationVerifier.js";
+import { VerificationStatus } from "@unicitylabs/state-transition-sdk/lib/verification/VerificationStatus.js";
+import { VerificationResult } from "@unicitylabs/state-transition-sdk/lib/verification/VerificationResult.js";
+import { UnicityId } from "@unicitylabs/state-transition-sdk/lib/unicity-id/UnicityId.js";
+import { UnicityIdMintTransaction } from "@unicitylabs/state-transition-sdk/lib/unicity-id/UnicityIdMintTransaction.js";
+import { CertifiedUnicityIdMintTransaction } from "@unicitylabs/state-transition-sdk/lib/unicity-id/CertifiedUnicityIdMintTransaction.js";
+import { UnicityIdToken } from "@unicitylabs/state-transition-sdk/lib/unicity-id/UnicityIdToken.js";
+import { HexConverter } from "@unicitylabs/state-transition-sdk/lib/util/HexConverter.js";
+import { BigintConverter } from "@unicitylabs/state-transition-sdk/lib/util/BigintConverter.js";
+import { BitString } from "@unicitylabs/state-transition-sdk/lib/util/BitString.js";
+
+// token-engine/identity.ts
+var UNICITY_TOKEN_TYPE_HEX = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
+var SIGNING_ALGORITHM = "secp256k1";
+var EMBEDDED_PREDICATE_UNMASKED = 0;
+var HASH_ALGORITHM_SHA256 = 0n;
+var SHA256_IMPRINT_PREFIX = new Uint8Array([0, 0]);
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function sha256(data) {
+  return new DataHasher(HashAlgorithm.SHA256).update(data).digest().then((h) => h.data);
+}
+async function deriveDirectAddress(publicKey) {
+  const tokenTypeCbor = CborSerializer.encodeByteString(hexToBytes(UNICITY_TOKEN_TYPE_HEX));
+  const reference = CborSerializer.encodeArray(
+    CborSerializer.encodeByteString(new Uint8Array([EMBEDDED_PREDICATE_UNMASKED])),
+    CborSerializer.encodeByteString(tokenTypeCbor),
+    CborSerializer.encodeTextString(SIGNING_ALGORITHM),
+    CborSerializer.encodeUnsignedInteger(HASH_ALGORITHM_SHA256),
+    CborSerializer.encodeByteString(publicKey)
+  );
+  const refHash = await sha256(reference);
+  const imprint = new Uint8Array([...SHA256_IMPRINT_PREFIX, ...refHash]);
+  const checksum = (await sha256(imprint)).slice(0, 4);
+  return `DIRECT://${HexConverter.encode(imprint)}${HexConverter.encode(checksum)}`;
+}
+
+// core/errors.ts
+var SphereError = class extends Error {
+  code;
+  cause;
+  constructor(message, code, cause) {
+    super(message);
+    this.name = "SphereError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+
+// core/logger.ts
+var LOGGER_KEY = "__sphere_sdk_logger__";
+function getState() {
+  const g = globalThis;
+  if (!g[LOGGER_KEY]) {
+    g[LOGGER_KEY] = { debug: false, tags: {}, handler: null };
+  }
+  return g[LOGGER_KEY];
+}
+function isEnabled(tag) {
+  const state = getState();
+  if (tag in state.tags) return state.tags[tag];
+  return state.debug;
+}
+var logger = {
+  /**
+   * Configure the logger. Can be called multiple times (last write wins).
+   * Typically called by createBrowserProviders(), createNodeProviders(), or Sphere.init().
+   */
+  configure(config) {
+    const state = getState();
+    if (config.debug !== void 0) state.debug = config.debug;
+    if (config.handler !== void 0) state.handler = config.handler;
+  },
+  /**
+   * Enable/disable debug logging for a specific tag.
+   * Per-tag setting overrides the global debug flag.
+   *
+   * @example
+   * ```ts
+   * logger.setTagDebug('Nostr', true);  // enable only Nostr logs
+   * logger.setTagDebug('Nostr', false); // disable Nostr logs even if global debug=true
+   * ```
+   */
+  setTagDebug(tag, enabled) {
+    getState().tags[tag] = enabled;
+  },
+  /**
+   * Clear per-tag override, falling back to global debug flag.
+   */
+  clearTagDebug(tag) {
+    delete getState().tags[tag];
+  },
+  /** Returns true if debug mode is enabled for the given tag (or globally). */
+  isDebugEnabled(tag) {
+    if (tag) return isEnabled(tag);
+    return getState().debug;
+  },
+  /**
+   * Debug-level log. Only shown when debug is enabled (globally or for this tag).
+   * Use for detailed operational information.
+   */
+  debug(tag, message, ...args) {
+    if (!isEnabled(tag)) return;
+    const state = getState();
+    if (state.handler) {
+      state.handler("debug", tag, message, ...args);
+    } else {
+      console.log(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Warning-level log. ALWAYS shown regardless of debug flag.
+   * Use for important but non-critical issues (timeouts, retries, degraded state).
+   */
+  warn(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("warn", tag, message, ...args);
+    } else {
+      console.warn(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Error-level log. ALWAYS shown regardless of debug flag.
+   * Use for critical failures that should never be silenced.
+   */
+  error(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("error", tag, message, ...args);
+    } else {
+      console.error(`[${tag}]`, message, ...args);
+    }
+  },
+  /** Reset all logger state (debug flag, tags, handler). Primarily for tests. */
+  reset() {
+    const g = globalThis;
+    delete g[LOGGER_KEY];
+  }
+};
+
+// token-engine/SpherePaymentData.ts
+var COIN_ID_PATTERN = /^([0-9a-f]{2})+$/;
+function assertAsset(coinId, amount) {
+  if (!COIN_ID_PATTERN.test(coinId)) {
+    throw new SphereError(`Invalid coin id (expected even-length lowercase hex): "${coinId}"`, "VALIDATION_ERROR");
+  }
+  if (amount < 0n) {
+    throw new SphereError(`Asset amount must be non-negative: ${amount.toString()}`, "VALIDATION_ERROR");
+  }
+}
+function sphereAssetToSdk(coinId, amount) {
+  assertAsset(coinId, amount);
+  return new Asset(new AssetId(HexConverter.decode(coinId)), amount);
+}
+var SpherePaymentData = class _SpherePaymentData {
+  constructor(assets, _memo = null) {
+    this.assets = assets;
+    this._memo = _memo;
+  }
+  /** Sphere-private CBOR tag (verified free in the v2 SDK tag space). */
+  static CBOR_TAG = 39050n;
+  /** Envelope version; bump when the structure changes. */
+  static VERSION = 1n;
+  /** Opaque, app-defined memo carried alongside the value (e.g. invoice attribution). */
+  get memo() {
+    return this._memo ? new Uint8Array(this._memo) : null;
+  }
+  /** Wrap an existing SDK asset collection (+ optional opaque memo). */
+  static create(assets, memo = null) {
+    return new _SpherePaymentData(assets, memo);
+  }
+  /** Build from a sphere-domain value (hex coin id → bigint amount) + optional opaque memo. */
+  static fromValue(value, memo = null) {
+    const assets = value.assets.map((a) => sphereAssetToSdk(a.coinId, a.amount));
+    return new _SpherePaymentData(PaymentAssetCollection.create(...assets), memo);
+  }
+  /** Decode from the CBOR envelope produced by {@link encode}. */
+  static fromCBOR(bytes) {
+    const tag = CborDeserializer.decodeTag(bytes);
+    if (tag.tag !== _SpherePaymentData.CBOR_TAG) {
+      throw new CborError(`Invalid SpherePaymentData tag: ${tag.tag}`);
+    }
+    const fields = CborDeserializer.decodeArray(tag.data, 3);
+    const version = CborDeserializer.decodeUnsignedInteger(fields[0]);
+    if (version !== _SpherePaymentData.VERSION) {
+      throw new CborError(`Unsupported SpherePaymentData version: ${version}`);
+    }
+    const memo = CborDeserializer.decodeNullable(fields[2], CborDeserializer.decodeByteString);
+    return new _SpherePaymentData(PaymentAssetCollection.fromCBOR(fields[1]), memo);
+  }
+  /** Deterministic, versioned, tagged CBOR: `tag(39050)[ version, assets, memo? ]`. */
+  encode() {
+    return Promise.resolve(
+      CborSerializer.encodeTag(
+        _SpherePaymentData.CBOR_TAG,
+        CborSerializer.encodeArray(
+          CborSerializer.encodeUnsignedInteger(_SpherePaymentData.VERSION),
+          this.assets.toCBOR(),
+          CborSerializer.encodeNullable(this._memo, CborSerializer.encodeByteString)
+        )
+      )
+    );
+  }
+  /** Project to a sphere-domain value (hex coin id + bigint amount), preserving order. */
+  toValue() {
+    return {
+      assets: this.assets.toArray().map((a) => ({
+        coinId: HexConverter.encode(a.id.bytes),
+        amount: a.value
+      }))
+    };
+  }
+  /** Balance of a single coin within this payload (0n when absent). */
+  balanceOf(coinId) {
+    if (!COIN_ID_PATTERN.test(coinId)) {
+      throw new SphereError(`Invalid coin id (expected even-length lowercase hex): "${coinId}"`, "VALIDATION_ERROR");
+    }
+    const asset = this.assets.get(new AssetId(HexConverter.decode(coinId)));
+    return asset ? asset.value : 0n;
+  }
+};
+function decodeSpherePaymentData(bytes) {
+  return Promise.resolve(SpherePaymentData.fromCBOR(bytes));
+}
+
+// token-engine/token-blob.ts
+var TOKEN_BLOB_VERSION = 1;
+
+// token-engine/SphereTokenEngine.ts
+var SphereTokenEngine = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  // ── identity ────────────────────────────────────────────────────────────────
+  getIdentity() {
+    return { chainPubkey: new Uint8Array(this.deps.signingService.publicKey) };
+  }
+  /** Legacy DIRECT:// address (Path A). Async: the derivation hashes via the SDK. */
+  deriveIdentityAddress(pubkey) {
+    return deriveDirectAddress(pubkey ?? this.deps.signingService.publicKey);
+  }
+  // ── value (read) ─────────────────────────────────────────────────────────────
+  readValue(token) {
+    return token.value;
+  }
+  balanceOf(token, coinId) {
+    let sum = 0n;
+    for (const asset of token.value?.assets ?? []) {
+      if (asset.coinId === coinId) sum += asset.amount;
+    }
+    return sum;
+  }
+  tokenId(token) {
+    return token.blob.tokenId;
+  }
+  readMemo(token) {
+    const sdkToken = token.sdkToken;
+    if (sdkToken.transactions.length > 0) {
+      return sdkToken.latestTransaction.data;
+    }
+    const data = sdkToken.genesis.data;
+    if (data && this.isSpherePaymentData(data)) {
+      return SpherePaymentData.fromCBOR(data).memo;
+    }
+    return null;
+  }
+  readTokenData(token) {
+    const data = token.sdkToken.genesis.data;
+    return data ? new Uint8Array(data) : null;
+  }
+  // ── lifecycle ────────────────────────────────────────────────────────────────
+  async mint(params, options) {
+    const recipient = SignaturePredicate.create(params.recipientPubkey);
+    const data = params.value ? await SpherePaymentData.fromValue(params.value).encode() : null;
+    const mintTx = await MintTransaction.create(this.deps.networkId, recipient, data);
+    const certificationData = await CertificationData.fromMintTransaction(mintTx);
+    const response = await this.deps.client.submitCertificationRequest(certificationData);
+    if (response.status !== CertificationStatus.SUCCESS) {
+      throw new SphereError(`Mint certification failed: ${response.status}`, "AGGREGATOR_ERROR");
+    }
+    const proof = await waitInclusionProof(
+      this.deps.client,
+      this.deps.trustBase,
+      this.deps.predicateVerifier,
+      mintTx,
+      options?.signal
+    );
+    const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, proof);
+    const token = await Token.mint(
+      this.deps.trustBase,
+      this.deps.predicateVerifier,
+      this.deps.mintJustificationVerifier,
+      certified
+    );
+    return this.wrapToken(token);
+  }
+  async mintDataToken(params, options) {
+    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 certificationData = await CertificationData.fromMintTransaction(mintTx);
+    const response = await this.deps.client.submitCertificationRequest(certificationData);
+    if (response.status !== CertificationStatus.SUCCESS) {
+      throw new SphereError(`Data-token mint failed: ${response.status}`, "AGGREGATOR_ERROR");
+    }
+    const proof = await waitInclusionProof(
+      this.deps.client,
+      this.deps.trustBase,
+      this.deps.predicateVerifier,
+      mintTx,
+      options?.signal
+    );
+    const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, proof);
+    const token = await Token.mint(
+      this.deps.trustBase,
+      this.deps.predicateVerifier,
+      this.deps.mintJustificationVerifier,
+      certified
+    );
+    return this.wrapToken(token);
+  }
+  async transfer(params, options) {
+    this.assertOwned(params.token);
+    const recipient = SignaturePredicate.create(params.recipientPubkey);
+    const stateMask = crypto.getRandomValues(new Uint8Array(32));
+    const transferTx = await TransferTransaction.create(params.token.sdkToken, recipient, stateMask, params.data ?? null);
+    const unlockScript = await SignaturePredicateUnlockScript.create(transferTx, this.deps.signingService);
+    const certificationData = await CertificationData.fromTransaction(transferTx, unlockScript);
+    const response = await this.deps.client.submitCertificationRequest(certificationData);
+    if (response.status !== CertificationStatus.SUCCESS) {
+      throw new SphereError(`Transfer certification failed: ${response.status}`, "TRANSFER_FAILED");
+    }
+    const proof = await waitInclusionProof(
+      this.deps.client,
+      this.deps.trustBase,
+      this.deps.predicateVerifier,
+      transferTx,
+      options?.signal
+    );
+    const certified = await transferTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, proof);
+    const transferred = await params.token.sdkToken.transfer(this.deps.trustBase, this.deps.predicateVerifier, certified);
+    return this.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");
+    }
+    const requests = params.outputs.map(
+      (o) => SplitTokenRequest.create(
+        SignaturePredicate.create(o.recipientPubkey),
+        PaymentAssetCollection.create(sphereAssetToSdk(o.coinId, o.amount))
+      )
+    );
+    const split = await TokenSplit.split(params.token.sdkToken, decodeSpherePaymentData, requests);
+    const burnUnlock = await SignaturePredicateUnlockScript.create(split.burn.transaction, this.deps.signingService);
+    const burnCert = await CertificationData.fromTransaction(split.burn.transaction, burnUnlock);
+    const burnResponse = await this.deps.client.submitCertificationRequest(burnCert);
+    if (burnResponse.status !== CertificationStatus.SUCCESS) {
+      throw new SphereError(`Split burn failed: ${burnResponse.status}`, "TRANSFER_FAILED");
+    }
+    const burnProof = await waitInclusionProof(
+      this.deps.client,
+      this.deps.trustBase,
+      this.deps.predicateVerifier,
+      split.burn.transaction,
+      options?.signal
+    );
+    const burnCertified = await split.burn.transaction.toCertifiedTransaction(
+      this.deps.trustBase,
+      this.deps.predicateVerifier,
+      burnProof
+    );
+    const burntToken = await params.token.sdkToken.transfer(
+      this.deps.trustBase,
+      this.deps.predicateVerifier,
+      burnCertified
+    );
+    const outputs = [];
+    for (let i = 0; i < split.tokens.length; i++) {
+      const splitToken = split.tokens[i];
+      const data = await SpherePaymentData.create(splitToken.assets, params.outputs[i].data ?? null).encode();
+      const justification = SplitMintJustification.create(burntToken, splitToken.proofs).toCBOR();
+      const mintTx = await MintTransaction.create(
+        splitToken.networkId,
+        splitToken.recipient,
+        data,
+        splitToken.tokenType,
+        splitToken.salt,
+        justification
+      );
+      const certData = await CertificationData.fromMintTransaction(mintTx);
+      const response = await this.deps.client.submitCertificationRequest(certData);
+      if (response.status !== CertificationStatus.SUCCESS) {
+        throw new SphereError(`Split mint failed: ${response.status}`, "AGGREGATOR_ERROR");
+      }
+      const proof = await waitInclusionProof(
+        this.deps.client,
+        this.deps.trustBase,
+        this.deps.predicateVerifier,
+        mintTx,
+        options?.signal
+      );
+      const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, proof);
+      const token = await Token.mint(
+        this.deps.trustBase,
+        this.deps.predicateVerifier,
+        this.deps.mintJustificationVerifier,
+        certified
+      );
+      outputs.push(this.wrapToken(token));
+    }
+    return { outputs };
+  }
+  // ── verification ─────────────────────────────────────────────────────────────
+  async verify(token, _options) {
+    const result = await token.sdkToken.verify(
+      this.deps.trustBase,
+      this.deps.predicateVerifier,
+      this.deps.mintJustificationVerifier
+    );
+    return result.status === VerificationStatus.OK ? { ok: true } : { ok: false, reason: String(result.status) };
+  }
+  isOwnedBy(token, pubkey) {
+    const owner = token.sdkToken.latestTransaction.recipient;
+    const claimed = EncodedPredicate.fromPredicate(SignaturePredicate.create(pubkey));
+    return EncodedPredicate.equals(owner, claimed);
+  }
+  async isSpent(token, _options) {
+    const probe = await TransferTransaction.create(
+      token.sdkToken,
+      SignaturePredicate.create(this.deps.signingService.publicKey),
+      new Uint8Array(32)
+    );
+    const stateId = await StateId.fromTransaction(probe);
+    const response = await this.deps.client.getInclusionProof(stateId);
+    return response.inclusionProof.inclusionCertificate !== null;
+  }
+  // ── serialization ────────────────────────────────────────────────────────────
+  encodeToken(token) {
+    return token.blob;
+  }
+  async decodeToken(blob) {
+    const sdkToken = await Token.fromCBOR(blob.token);
+    if (sdkToken.genesis.networkId.id !== this.deps.networkId.id) {
+      throw new SphereError(
+        `Token network mismatch: token is on network ${sdkToken.genesis.networkId.id}, engine on ${this.deps.networkId.id}`,
+        "VALIDATION_ERROR"
+      );
+    }
+    return this.wrapToken(sdkToken);
+  }
+  // ── internals ────────────────────────────────────────────────────────────────
+  /** Fail fast if this engine's key does not own the token's current state. */
+  assertOwned(token) {
+    if (!this.isOwnedBy(token, this.deps.signingService.publicKey)) {
+      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 = {
+      v: TOKEN_BLOB_VERSION,
+      network: sdkToken.genesis.networkId.id,
+      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;
+    }
+  }
+};
+
+// token-engine/factory.ts
+async function createSphereTokenEngine(config) {
+  if (config.trustBaseJson == null) {
+    throw new SphereError("Engine config requires a trust base (trustBaseJson)", "INVALID_CONFIG");
+  }
+  if (!config.apiKey) {
+    logger.warn(
+      "TokenEngine",
+      "No aggregator apiKey \u2014 pass config.oracle.apiKey (testnet2 value in .env.example; mainnet from a secret env var). Gateway requests will be unauthenticated."
+    );
+  }
+  const trustBase = RootTrustBase.fromJSON(config.trustBaseJson);
+  const predicateVerifier = PredicateVerifierService.create();
+  const mintJustificationVerifier = new MintJustificationVerifierService();
+  mintJustificationVerifier.register(
+    new SplitMintJustificationVerifier(trustBase, predicateVerifier, decodeSpherePaymentData)
+  );
+  const deps = {
+    client: new StateTransitionClient(new AggregatorClient(config.aggregatorUrl, config.apiKey ?? null)),
+    trustBase,
+    predicateVerifier,
+    mintJustificationVerifier,
+    signingService: new SigningService(config.privateKey),
+    // The trust base is the single source of truth for the network id (it carries
+    // NetworkId.fromId, so any id works — e.g. testnet2 = 4 — with no enum entry).
+    networkId: trustBase.networkId
+  };
+  return new SphereTokenEngine(deps);
+}
+
+// token-engine/unicity-id.ts
+var SelfIssuedUnicityIdMinter = class {
+  constructor(client, trustBase, predicateVerifier, signingService) {
+    this.client = client;
+    this.trustBase = trustBase;
+    this.predicateVerifier = predicateVerifier;
+    this.signingService = signingService;
+  }
+  async mintUnicityIdToken(name, options) {
+    const unicityId = new UnicityId(name);
+    const self = SignaturePredicate.fromSigningService(this.signingService);
+    const mintTx = await UnicityIdMintTransaction.create(
+      self,
+      // issuer lock script (self-issued)
+      self,
+      // recipient — locks the minted token state to this wallet
+      unicityId,
+      new TokenType(HexConverter.decode(UNICITY_TOKEN_TYPE_HEX)),
+      self
+      // target predicate the unicity id resolves to
+    );
+    const certificationData = await CertificationData.fromTransaction(
+      mintTx,
+      await SignaturePredicateUnlockScript.create(mintTx, this.signingService)
+    );
+    const response = await this.client.submitCertificationRequest(certificationData);
+    if (response.status !== CertificationStatus.SUCCESS) {
+      logger.warn(
+        "UnicityIdMinter",
+        `Certification request returned ${response.status} for "@${name}" \u2014 attempting proof recovery (idempotent re-mint).`
+      );
+    }
+    try {
+      const proof = await waitInclusionProof(
+        this.client,
+        this.trustBase,
+        this.predicateVerifier,
+        mintTx,
+        options?.signal
+      );
+      const certified = await mintTx.toCertifiedTransaction(this.trustBase, this.predicateVerifier, proof);
+      const token = await UnicityIdToken.mint(this.trustBase, this.predicateVerifier, certified);
+      return {
+        tokenCborHex: HexConverter.encode(token.toCBOR()),
+        tokenId: HexConverter.encode(token.id.bytes)
+      };
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new SphereError(
+        `Unicity ID mint failed for "@${name}": ${detail}` + (response.status !== CertificationStatus.SUCCESS ? ` (certification status: ${response.status})` : ""),
+        "AGGREGATOR_ERROR"
+      );
+    }
+  }
+};
+function createUnicityIdMinter(config) {
+  if (config.trustBaseJson == null) {
+    throw new SphereError("Unicity ID minter requires a trust base (trustBaseJson)", "INVALID_CONFIG");
+  }
+  const trustBase = RootTrustBase.fromJSON(config.trustBaseJson);
+  return new SelfIssuedUnicityIdMinter(
+    new StateTransitionClient(new AggregatorClient(config.aggregatorUrl, config.apiKey ?? null)),
+    trustBase,
+    PredicateVerifierService.create(),
+    new SigningService(config.privateKey)
+  );
+}
+export {
+  SpherePaymentData,
+  createSphereTokenEngine,
+  createUnicityIdMinter,
+  decodeSpherePaymentData,
+  deriveDirectAddress,
+  sphereAssetToSdk
+};
+//# sourceMappingURL=index.js.map