@unicitylabs/sphere-sdk 0.18.0-dev.2 → 0.18.0-dev.3

package/dist/token-engine/index.cjs

@@ -22,6 +22,7 @@ var token_engine_exports = {};
 __export(token_engine_exports, {
   CheckpointPersistFailedError: () => CheckpointPersistFailedError,
   CheckpointTrustbaseMismatchError: () => CheckpointTrustbaseMismatchError,
+  MintReasonUnverifiableError: () => MintReasonUnverifiableError,
   NFT_DOCUMENT_MEDIA_TYPE: () => NFT_DOCUMENT_MEDIA_TYPE,
   NFT_FORMAT_VERSION: () => NFT_FORMAT_VERSION,
   NFT_LINK_TAG: () => NFT_LINK_TAG,
@@ -252,6 +253,150 @@ var logger = {
   }
 };
 
+// token-engine/claims.ts
+var CoinClaims = class _CoinClaims {
+  issuers = /* @__PURE__ */ new Map();
+  policies = [];
+  static fromPlugins(plugins) {
+    const claims = new _CoinClaims();
+    for (const plugin of plugins ?? []) {
+      for (const policy of plugin.tokenIssuancePolicies ?? []) claims.add(policy);
+    }
+    return claims;
+  }
+  add(policy) {
+    const tokenType = import_HexConverter.HexConverter.encode(policy.tokenType.bytes);
+    const coinIds = policy.coinIds.map((coinId) => coinId.toLowerCase());
+    const taken = coinIds.find((coinId) => this.issuers.has(coinId));
+    if (taken !== void 0) throw new Error(`Coin ${taken} is already issued by token type ${this.issuers.get(taken)}.`);
+    for (const coinId of coinIds) this.issuers.set(coinId, tokenType);
+    this.policies.push(JSON.stringify([tokenType, [...coinIds].sort(), policy.revision ?? ""]));
+  }
+  fingerprint() {
+    return [...this.policies].sort().join("\n");
+  }
+  issuerOf(coinId) {
+    return this.issuers.get(coinId.toLowerCase()) ?? null;
+  }
+};
+
+// token-engine/errors.ts
+var TransferConflictError = class extends SphereError {
+  /**
+   * #625: the source token id (the caller's id, e.g. `v2_<genesis>`) whose state was already spent.
+   * Set by PaymentsModule at the engine call site so the self-healing retry can demote it and re-plan.
+   */
+  conflictedSourceId;
+  constructor(message, cause) {
+    super(message, "TRANSFER_CONFLICT", cause);
+    this.name = "TransferConflictError";
+  }
+};
+var MintReasonUnverifiableError = class extends SphereError {
+  constructor(message, cause) {
+    super(message, "MINT_REASON_UNVERIFIABLE", cause);
+    this.name = "MintReasonUnverifiableError";
+  }
+};
+var ProofUnconfirmedError = class extends SphereError {
+  mayHaveCertified = true;
+  constructor(message, cause) {
+    super(message, "CERTIFICATION_UNCONFIRMED", cause);
+    this.name = "ProofUnconfirmedError";
+  }
+};
+var CheckpointPersistFailedError = class extends SphereError {
+  mayHaveCertified = true;
+  constructor(message, cause) {
+    super(message, "CHECKPOINT_PERSIST_FAILED", cause);
+    this.name = "CheckpointPersistFailedError";
+  }
+};
+var SplitCheckpointLostError = class extends SphereError {
+  constructor(message, cause) {
+    super(message, "SPLIT_CHECKPOINT_LOST", cause);
+    this.name = "SplitCheckpointLostError";
+  }
+};
+var CheckpointTrustbaseMismatchError = class extends SphereError {
+  constructor(message, cause) {
+    super(message, "CHECKPOINT_TRUSTBASE_MISMATCH", cause);
+    this.name = "CheckpointTrustbaseMismatchError";
+  }
+};
+function isKeepOpenSplitError(err) {
+  return err instanceof ProofUnconfirmedError || err instanceof CheckpointPersistFailedError || err instanceof SplitCheckpointLostError || err instanceof CheckpointTrustbaseMismatchError;
+}
+
+// token-engine/mint-reasons.ts
+var RULE = "MintJustificationVerification";
+var MintReasonRegistry = class _MintReasonRegistry extends import_MintJustificationVerifierService.MintJustificationVerifierService {
+  byTag = /* @__PURE__ */ new Map();
+  pluginTags = /* @__PURE__ */ new Set();
+  register(verifier) {
+    super.register(verifier);
+    this.byTag.set(verifier.tag, verifier);
+    return this;
+  }
+  registerPlugin(verifier) {
+    this.register(verifier);
+    this.pluginTags.add(verifier.tag);
+    return this;
+  }
+  async verify(transaction, nestedTokenCollector) {
+    const tag = transaction.justification ? reasonTag(transaction.justification) : null;
+    if (tag === null) return super.verify(transaction, nestedTokenCollector);
+    const verifier = this.byTag.get(tag);
+    if (verifier === void 0) throw new MintReasonUnverifiableError(`No verifier is registered for mint-reason tag ${tag}`);
+    if (!this.pluginTags.has(tag)) return super.verify(transaction, nestedTokenCollector);
+    return verifyPlugin(verifier, transaction, nestedTokenCollector);
+  }
+  knows(tag) {
+    return this.byTag.has(tag);
+  }
+  /** `verifiers` replace the registered ones of their tags; a tag this registry lacks is refused. */
+  overlaid(verifiers) {
+    for (const verifier of verifiers) assertKnown(this, verifier.tag);
+    const replaced = new Map(verifiers.map((verifier) => [verifier.tag, verifier]));
+    const overlay = new _MintReasonRegistry();
+    for (const [tag, verifier] of this.byTag) {
+      const perCall = replaced.get(tag);
+      if (perCall !== void 0 || this.pluginTags.has(tag)) overlay.registerPlugin(perCall ?? verifier);
+      else overlay.register(verifier);
+    }
+    return overlay;
+  }
+  assertVerifiable(justification) {
+    const tag = reasonTag(justification);
+    if (tag === null) throw new SphereError("The mint reason is not tagged CBOR", "VALIDATION_ERROR");
+    assertKnown(this, tag);
+  }
+};
+function reasonTag(justification) {
+  try {
+    return BigInt(import_CborDeserializer.CborDeserializer.decodeTag(justification).tag);
+  } catch {
+    return null;
+  }
+}
+async function verifyPlugin(verifier, transaction, nestedTokenCollector) {
+  let result;
+  try {
+    result = await verifier.verify(transaction, nestedTokenCollector);
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    throw new MintReasonUnverifiableError(`Mint-reason tag ${verifier.tag} cannot be verified yet: ${why}`, err);
+  }
+  return result.status === import_VerificationStatus.VerificationStatus.OK ? new import_VerificationResult.VerificationResult(RULE, import_VerificationStatus.VerificationStatus.OK, "", [result]) : new import_VerificationResult.VerificationResult(RULE, import_VerificationStatus.VerificationStatus.FAIL, `Verification failed for tag ${verifier.tag}.`, [result]);
+}
+function assertKnown(registry, tag) {
+  if (registry.knows(tag)) return;
+  throw new SphereError(
+    `No verifier is registered on the engine for mint-reason tag ${tag}, so a replay of this mint could never verify`,
+    "VALIDATION_ERROR"
+  );
+}
+
 // token-engine/SpherePaymentData.ts
 var COIN_ID_PATTERN = /^([0-9a-f]{2})+$/;
 function assertAsset(coinId, amount) {
@@ -772,45 +917,6 @@ async function awaitProofBounded(deps, transaction, signal) {
   return value;
 }
 
-// token-engine/errors.ts
-var TransferConflictError = class extends SphereError {
-  /**
-   * #625: the source token id (the caller's id, e.g. `v2_<genesis>`) whose state was already spent.
-   * Set by PaymentsModule at the engine call site so the self-healing retry can demote it and re-plan.
-   */
-  conflictedSourceId;
-  constructor(message, cause) {
-    super(message, "TRANSFER_CONFLICT", cause);
-    this.name = "TransferConflictError";
-  }
-};
-var ProofUnconfirmedError = class extends SphereError {
-  mayHaveCertified = true;
-  constructor(message, cause) {
-    super(message, "CERTIFICATION_UNCONFIRMED", cause);
-    this.name = "ProofUnconfirmedError";
-  }
-};
-var CheckpointPersistFailedError = class extends SphereError {
-  mayHaveCertified = true;
-  constructor(message, cause) {
-    super(message, "CHECKPOINT_PERSIST_FAILED", cause);
-    this.name = "CheckpointPersistFailedError";
-  }
-};
-var SplitCheckpointLostError = class extends SphereError {
-  constructor(message, cause) {
-    super(message, "SPLIT_CHECKPOINT_LOST", cause);
-    this.name = "SplitCheckpointLostError";
-  }
-};
-var CheckpointTrustbaseMismatchError = class extends SphereError {
-  constructor(message, cause) {
-    super(message, "CHECKPOINT_TRUSTBASE_MISMATCH", cause);
-    this.name = "CheckpointTrustbaseMismatchError";
-  }
-};
-
 // token-engine/certification-outcome.ts
 function certificationFailure(err, failLabel, submitError, submitRejectedCleanly) {
   if (err instanceof Error && err.message === `Invalid inclusion proof status: ${import_InclusionProofVerificationRule.InclusionProofVerificationStatus.TRANSACTION_HASH_MISMATCH}`) {
@@ -1475,15 +1581,17 @@ async function readTokenNft(token) {
 }
 
 // token-engine/plugin-ops.ts
-function contextWithMintVerifiers(base, verifiers) {
-  const registry = new import_MintJustificationVerifierService.MintJustificationVerifierService();
-  for (const verifier of verifiers) registry.register(verifier);
+function mintContext(deps, params) {
+  assertMintableData(params.data);
+  if (params.justification !== void 0) deps.mintJustificationVerifier.assertVerifiable(params.justification);
+  const verifiers = params.mintJustificationVerifiers;
+  if (verifiers === void 0) return deps.verificationContext;
   return new import_VerificationContext.VerificationContext(
-    base.trustBase,
-    base.predicateVerifier,
-    base.unicityCertificateVerifier,
-    registry,
-    new import_TokenIssuanceVerifierService.TokenIssuanceVerifierService(false)
+    deps.trustBase,
+    deps.predicateVerifier,
+    deps.unicityCertificateVerifier,
+    deps.mintJustificationVerifier.overlaid(verifiers),
+    deps.verificationContext.tokenIssuanceVerifier
   );
 }
 
@@ -1571,9 +1679,6 @@ async function burntTokenFromCheckpoint(deps, storedBytes, reDerivedBurnTx, sour
 // token-engine/SphereTokenEngine.ts
 var DEFAULT_PROOF_POLL_INTERVAL_MS = 300;
 var MAX_MINT_CONCURRENCY = 8;
-function isKeepOpenSplitError(err) {
-  return err instanceof ProofUnconfirmedError || err instanceof CheckpointPersistFailedError || err instanceof SplitCheckpointLostError || err instanceof CheckpointTrustbaseMismatchError;
-}
 var TRANSFER_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 var CLEAN_REJECT_STATUSES = /* @__PURE__ */ new Set([
   import_CertificationResponse.CertificationStatus.STATE_ID_MISMATCH,
@@ -1663,8 +1768,9 @@ var SphereTokenEngine = class {
     const token = await import_Token.Token.mint(certified, this.deps.verificationContext);
     return wrapToken(token);
   }
+  assertMintable = (params) => void mintContext(this.deps, params);
   async mintDataToken(params, options) {
-    assertMintableData(params.data);
+    const context = mintContext(this.deps, params);
     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();
@@ -1678,8 +1784,7 @@ var SphereTokenEngine = class {
       options
     );
     const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
-    const verifiers = params.mintJustificationVerifiers;
-    return wrapToken(await import_Token.Token.mint(certified, verifiers ? contextWithMintVerifiers(this.deps, verifiers) : this.deps.verificationContext));
+    return wrapToken(await import_Token.Token.mint(certified, context));
   }
   buildNftMint(params) {
     return planNftMint(this.deps, params);
@@ -2016,20 +2121,30 @@ var SphereTokenEngine = class {
 
 // token-engine/factory.ts
 var DEFAULT_VERIFICATION_POOL_SIZE = 4;
-function registerPluginVerifiers(registry, plugins) {
+function registerPlugins(registries, plugins) {
   for (const plugin of plugins ?? []) {
     for (const verifier of plugin.mintJustificationVerifiers ?? []) {
-      try {
-        registry.register(verifier);
-      } catch (err) {
-        throw new SphereError(
-          `Token plugin '${plugin.id}' registers mint-reason tag ${verifier.tag} twice or over another plugin's: ` + (err instanceof Error ? err.message : String(err)),
-          "INVALID_CONFIG"
-        );
-      }
+      claim(plugin, `mint-reason tag ${verifier.tag}`, () => registries.reasons.registerPlugin(verifier));
+    }
+    for (const policy of plugin.tokenIssuancePolicies ?? []) {
+      const tokenType = import_HexConverter.HexConverter.encode(policy.tokenType.bytes);
+      claim(plugin, `an issuance policy for token type ${tokenType}`, () => {
+        registries.claims.add(policy);
+        registries.policies.register(policy);
+      });
     }
   }
 }
+function claim(plugin, what, register) {
+  try {
+    register();
+  } catch (err) {
+    throw new SphereError(
+      `Token plugin '${plugin.id}' registers ${what} twice or over another plugin's: ` + (err instanceof Error ? err.message : String(err)),
+      "INVALID_CONFIG"
+    );
+  }
+}
 function disposedError() {
   return new SphereError(
     "Verification worker pool disposed \u2014 the in-flight verification was cancelled",
@@ -2107,11 +2222,15 @@ async function createSphereTokenEngine(config) {
   const unicityCertificateVerifier = new import_UnicityCertificateVerifier.UnicityCertificateVerifier(
     new import_UnicitySealQuorumSignaturesVerificationRule.UnicitySealQuorumSignaturesVerificationRule(new import_Secp256k1SignatureVerifier.Secp256k1SignatureVerifier(), new import_VerifiedSealCache.VerifiedSealCache(256))
   );
-  const mintJustificationVerifier = new import_MintJustificationVerifierService.MintJustificationVerifierService();
+  const mintJustificationVerifier = new MintReasonRegistry();
   mintJustificationVerifier.register(
     new import_SplitMintJustificationVerifier.SplitMintJustificationVerifier(decodeSpherePaymentData)
   );
-  registerPluginVerifiers(mintJustificationVerifier, config.plugins);
+  const tokenIssuanceVerifier = new import_TokenIssuanceVerifierService.TokenIssuanceVerifierService(false);
+  registerPlugins(
+    { reasons: mintJustificationVerifier, policies: tokenIssuanceVerifier, claims: new CoinClaims() },
+    config.plugins
+  );
   const deps = {
     client: new import_StateTransitionClient.StateTransitionClient(new import_AggregatorClient.AggregatorClient(config.aggregatorUrl, config.apiKey ?? null)),
     trustBase,
@@ -2123,7 +2242,7 @@ async function createSphereTokenEngine(config) {
       predicateVerifier,
       unicityCertificateVerifier,
       mintJustificationVerifier,
-      new import_TokenIssuanceVerifierService.TokenIssuanceVerifierService(false)
+      tokenIssuanceVerifier
     ),
     signingService: new import_SigningService.SigningService(config.privateKey),
     // Also the HKDF ikm for deterministic realization (Part E.1) — the
@@ -2145,6 +2264,7 @@ async function createSphereTokenEngine(config) {
 0 && (module.exports = {
   CheckpointPersistFailedError,
   CheckpointTrustbaseMismatchError,
+  MintReasonUnverifiableError,
   NFT_DOCUMENT_MEDIA_TYPE,
   NFT_FORMAT_VERSION,
   NFT_LINK_TAG,