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

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

@@ -1,5 +1,7 @@
 import { IMintJustificationVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/IMintJustificationVerifier.js';
 export { IMintJustificationVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/IMintJustificationVerifier.js';
+import { ITokenIssuanceVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/ITokenIssuanceVerifier.js';
+export { ITokenIssuanceVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/ITokenIssuanceVerifier.js';
 import { DataHash } from '@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHash.js';
 import { Token } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
 import { IPaymentData } from '@unicitylabs/state-transition-sdk/lib/payment/IPaymentData.js';
@@ -202,12 +204,21 @@ interface BurnParams {
     /** The recipient predicate is `BurnPredicate(sha256(reasonBytes))`; the bytes ride in the aux data. */
     readonly reasonBytes: Uint8Array;
 }
+/** The issuance rule of one token type, and the coins no other type may carry. */
+interface TokenIssuancePolicy extends ITokenIssuanceVerifier {
+    /** A token carrying one of these coins counts only when it is of this type and verified. */
+    readonly coinIds: readonly CoinId[];
+    /** Must change whenever the proofs this policy accepts change, a fix to its verification code included, so wallets check held tokens again. */
+    readonly revision?: string;
+}
 /** Mint-reason verifiers keyed by CBOR tag, registered at engine construction. */
 interface TokenPlugin {
     /** Stable identifier for diagnostics, e.g. `'bridge:tron-usdt'`. */
     readonly id: string;
     /** Mint-reason verifiers to register; a duplicate tag across plugins is INVALID_CONFIG. */
     readonly mintJustificationVerifiers?: readonly IMintJustificationVerifier[];
+    /** Issuance policies to register; a duplicate token type or coin across plugins is INVALID_CONFIG. */
+    readonly tokenIssuancePolicies?: readonly TokenIssuancePolicy[];
 }
 /** Plan an NFT mint (#785); `mintDataToken` then mints the plan. */
 interface BuildNftMintParams {
@@ -403,6 +414,8 @@ interface ITokenEngine {
      * read its bytes via `readTokenData`. (Used e.g. for on-chain invoice tokens.)
      */
     mintDataToken(params: MintDataTokenParams, options?: EngineOpOptions): Promise<SphereToken>;
+    /** Throws VALIDATION_ERROR when `mintDataToken` would refuse `params` before submitting, e.g. a reason tag no registered verifier handles. */
+    assertMintable(params: MintDataTokenParams): void;
     /** Plan an NFT mint: encode (and optionally sign as this engine's identity) the payload and derive its token id. No chain op. */
     buildNftMint(params: BuildNftMintParams): Promise<NftMintPlan>;
     /** Spend a token wholesale to a recipient pubkey; returns the recipient's finished token. */
@@ -508,7 +521,7 @@ interface EngineConfig {
      * terminate the pool.
      */
     readonly verification?: VerificationWorkerConfig;
-    /** Token plugins whose mint-reason verifiers join the engine's verification context. */
+    /** Token plugins whose mint-reason verifiers and issuance policies join the engine's verification context. */
     readonly plugins?: readonly TokenPlugin[];
 }
 /** Factory signature for the real adapter (implemented in Track A). */
@@ -571,7 +584,7 @@ declare function createSphereTokenEngine(config: EngineConfig): Promise<ITokenEn
  * }
  * ```
  */
-type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'TRANSFER_CONFLICT' | 'CERTIFICATION_UNCONFIRMED' | 'CHECKPOINT_PERSIST_FAILED' | 'SPLIT_CHECKPOINT_LOST' | 'CHECKPOINT_TRUSTBASE_MISMATCH' | 'STORAGE_ERROR' | 'SEND_SYNC_PENDING' | 'SEND_PARTIALLY_COMPLETED' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'INVALID_AMOUNT' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'PAYMENTS_NOT_COMPOSED' | 'SIGNING_ERROR' | 'SEND_QUEUE_TIMEOUT' | 'SEND_INSUFFICIENT_BALANCE' | 'SEND_RESERVATION_CANCELLED' | 'SEND_QUEUE_FULL' | 'MODULE_DESTROYED' | 'REENTRANT_GATE' | 'INVOICE_NO_TARGETS' | 'INVOICE_INVALID_ADDRESS' | 'INVOICE_NO_ASSETS' | 'INVOICE_INVALID_ASSET' | 'INVOICE_INVALID_AMOUNT' | 'INVOICE_INVALID_COIN' | 'INVOICE_INVALID_NFT' | 'INVOICE_PAST_DUE_DATE' | 'INVOICE_DUPLICATE_ADDRESS' | 'INVOICE_DUPLICATE_COIN' | 'INVOICE_DUPLICATE_NFT' | 'INVOICE_MINT_FAILED' | 'INVOICE_INVALID_PROOF' | 'INVOICE_WRONG_TOKEN_TYPE' | 'INVOICE_INVALID_DATA' | 'INVOICE_ALREADY_EXISTS' | 'INVOICE_NOT_FOUND' | 'INVOICE_NOT_TARGET' | 'INVOICE_ALREADY_CLOSED' | 'INVOICE_ALREADY_CANCELLED' | 'INVOICE_ORACLE_REQUIRED' | 'INVOICE_TERMINATED' | 'INVOICE_INVALID_TARGET' | 'INVOICE_INVALID_ASSET_INDEX' | 'INVOICE_RETURN_EXCEEDS_BALANCE' | 'INVOICE_INVALID_DELIVERY_METHOD' | 'INVOICE_INVALID_REFUND_ADDRESS' | 'INVOICE_INVALID_CONTACT' | 'INVOICE_INVALID_ID' | 'INVOICE_TOO_MANY_TARGETS' | 'INVOICE_TOO_MANY_ASSETS' | 'INVOICE_MEMO_TOO_LONG' | 'INVOICE_TERMS_TOO_LARGE' | 'INVOICE_NOT_TERMINATED' | 'INVOICE_NOT_CANCELLED' | 'INVOICE_STORAGE_FAILED' | 'RATE_LIMITED' | 'COMMUNICATIONS_UNAVAILABLE' | 'SWAP_INVALID_DEAL' | 'SWAP_INVALID_MANIFEST' | 'SWAP_NOT_FOUND' | 'SWAP_WRONG_STATE' | 'SWAP_RESOLVE_FAILED' | 'SWAP_DM_SEND_FAILED' | 'SWAP_ESCROW_REJECTED' | 'SWAP_DEPOSIT_FAILED' | 'SWAP_PAYOUT_VERIFICATION_FAILED' | 'SWAP_ALREADY_EXISTS' | 'SWAP_ALREADY_COMPLETED' | 'SWAP_ALREADY_CANCELLED' | 'SWAP_TIMEOUT' | 'SWAP_LIMIT_EXCEEDED' | 'SWAP_ALREADY_INITIALIZED' | 'SWAP_MODULE_DESTROYED' | 'SWAP_NOT_INITIALIZED';
+type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'TRANSFER_CONFLICT' | 'CERTIFICATION_UNCONFIRMED' | 'CHECKPOINT_PERSIST_FAILED' | 'SPLIT_CHECKPOINT_LOST' | 'CHECKPOINT_TRUSTBASE_MISMATCH' | 'MINT_REASON_UNVERIFIABLE' | 'STORAGE_ERROR' | 'SEND_SYNC_PENDING' | 'SEND_PARTIALLY_COMPLETED' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'INVALID_AMOUNT' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'PAYMENTS_NOT_COMPOSED' | 'SIGNING_ERROR' | 'SEND_QUEUE_TIMEOUT' | 'SEND_INSUFFICIENT_BALANCE' | 'SEND_RESERVATION_CANCELLED' | 'SEND_QUEUE_FULL' | 'MODULE_DESTROYED' | 'REENTRANT_GATE' | 'INVOICE_NO_TARGETS' | 'INVOICE_INVALID_ADDRESS' | 'INVOICE_NO_ASSETS' | 'INVOICE_INVALID_ASSET' | 'INVOICE_INVALID_AMOUNT' | 'INVOICE_INVALID_COIN' | 'INVOICE_INVALID_NFT' | 'INVOICE_PAST_DUE_DATE' | 'INVOICE_DUPLICATE_ADDRESS' | 'INVOICE_DUPLICATE_COIN' | 'INVOICE_DUPLICATE_NFT' | 'INVOICE_MINT_FAILED' | 'INVOICE_INVALID_PROOF' | 'INVOICE_WRONG_TOKEN_TYPE' | 'INVOICE_INVALID_DATA' | 'INVOICE_ALREADY_EXISTS' | 'INVOICE_NOT_FOUND' | 'INVOICE_NOT_TARGET' | 'INVOICE_ALREADY_CLOSED' | 'INVOICE_ALREADY_CANCELLED' | 'INVOICE_ORACLE_REQUIRED' | 'INVOICE_TERMINATED' | 'INVOICE_INVALID_TARGET' | 'INVOICE_INVALID_ASSET_INDEX' | 'INVOICE_RETURN_EXCEEDS_BALANCE' | 'INVOICE_INVALID_DELIVERY_METHOD' | 'INVOICE_INVALID_REFUND_ADDRESS' | 'INVOICE_INVALID_CONTACT' | 'INVOICE_INVALID_ID' | 'INVOICE_TOO_MANY_TARGETS' | 'INVOICE_TOO_MANY_ASSETS' | 'INVOICE_MEMO_TOO_LONG' | 'INVOICE_TERMS_TOO_LARGE' | 'INVOICE_NOT_TERMINATED' | 'INVOICE_NOT_CANCELLED' | 'INVOICE_STORAGE_FAILED' | 'RATE_LIMITED' | 'COMMUNICATIONS_UNAVAILABLE' | 'SWAP_INVALID_DEAL' | 'SWAP_INVALID_MANIFEST' | 'SWAP_NOT_FOUND' | 'SWAP_WRONG_STATE' | 'SWAP_RESOLVE_FAILED' | 'SWAP_DM_SEND_FAILED' | 'SWAP_ESCROW_REJECTED' | 'SWAP_DEPOSIT_FAILED' | 'SWAP_PAYOUT_VERIFICATION_FAILED' | 'SWAP_ALREADY_EXISTS' | 'SWAP_ALREADY_COMPLETED' | 'SWAP_ALREADY_CANCELLED' | 'SWAP_TIMEOUT' | 'SWAP_LIMIT_EXCEEDED' | 'SWAP_ALREADY_INITIALIZED' | 'SWAP_MODULE_DESTROYED' | 'SWAP_NOT_INITIALIZED';
 declare class SphereError extends Error {
     readonly code: SphereErrorCode;
     readonly cause?: unknown;
@@ -623,6 +636,10 @@ declare class TransferConflictError extends SphereError {
  * certified proof + recipient blob, or records the spend if a foreign tx won the
  * race — never a second on-chain spend (sdk-changes E.2/E.3, #631).
  */
+/** A token's mint reason cannot be judged yet: no verifier for its tag here, or the plugin could not reach an answer. */
+declare class MintReasonUnverifiableError extends SphereError {
+    constructor(message: string, cause?: unknown);
+}
 declare class ProofUnconfirmedError extends SphereError {
     readonly mayHaveCertified: true;
     constructor(message: string, cause?: unknown);
@@ -715,4 +732,4 @@ declare class SpherePaymentData implements IPaymentData {
  */
 declare function decodeSpherePaymentData(bytes: Uint8Array): Promise<IPaymentData>;
 
-export { type BuildNftMintParams, type BurnParams, CheckpointPersistFailedError, CheckpointTrustbaseMismatchError, type CoinId, type CreateTokenEngine, type EngineConfig, type EngineIdentity, type EngineOpOptions, type EngineVerifyResult, type ITokenEngine, type MintDataTokenParams, type MintParams, NFT_DOCUMENT_MEDIA_TYPE, NFT_FORMAT_VERSION, NFT_LINK_TAG, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintPlan, type NftReading, type NftSignatureContext, type NftSignatureStatus, type ParsedNft, ProofUnconfirmedError, type SphereAsset, type SphereNetwork, SpherePaymentData, type SphereToken, type SphereValue, SplitCheckpointLostError, type SplitCheckpointStore, type SplitOutput, type SplitParams, type SplitResult, type TokenBlob, type TokenPlugin, TransferConflictError, type TransferParams, type VerificationWorker, type VerificationWorkerConfig, createSphereTokenEngine, decodeSpherePaymentData, deriveDirectAddress, encodeNftContent, encodeNftSigned, isNftDocumentLink, nftSignedDigest, parseNftDocument, parseNftPayload, sphereAssetToSdk, verifyNftLinkContent, verifyNftSignature };
+export { type BuildNftMintParams, type BurnParams, CheckpointPersistFailedError, CheckpointTrustbaseMismatchError, type CoinId, type CreateTokenEngine, type EngineConfig, type EngineIdentity, type EngineOpOptions, type EngineVerifyResult, type ITokenEngine, type MintDataTokenParams, type MintParams, MintReasonUnverifiableError, NFT_DOCUMENT_MEDIA_TYPE, NFT_FORMAT_VERSION, NFT_LINK_TAG, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintPlan, type NftReading, type NftSignatureContext, type NftSignatureStatus, type ParsedNft, ProofUnconfirmedError, type SphereAsset, type SphereNetwork, SpherePaymentData, type SphereToken, type SphereValue, SplitCheckpointLostError, type SplitCheckpointStore, type SplitOutput, type SplitParams, type SplitResult, type TokenBlob, type TokenIssuancePolicy, type TokenPlugin, TransferConflictError, type TransferParams, type VerificationWorker, type VerificationWorkerConfig, createSphereTokenEngine, decodeSpherePaymentData, deriveDirectAddress, encodeNftContent, encodeNftSigned, isNftDocumentLink, nftSignedDigest, parseNftDocument, parseNftPayload, sphereAssetToSdk, verifyNftLinkContent, verifyNftSignature };

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

@@ -1,5 +1,7 @@
 import { IMintJustificationVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/IMintJustificationVerifier.js';
 export { IMintJustificationVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/IMintJustificationVerifier.js';
+import { ITokenIssuanceVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/ITokenIssuanceVerifier.js';
+export { ITokenIssuanceVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/ITokenIssuanceVerifier.js';
 import { DataHash } from '@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHash.js';
 import { Token } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
 import { IPaymentData } from '@unicitylabs/state-transition-sdk/lib/payment/IPaymentData.js';
@@ -202,12 +204,21 @@ interface BurnParams {
     /** The recipient predicate is `BurnPredicate(sha256(reasonBytes))`; the bytes ride in the aux data. */
     readonly reasonBytes: Uint8Array;
 }
+/** The issuance rule of one token type, and the coins no other type may carry. */
+interface TokenIssuancePolicy extends ITokenIssuanceVerifier {
+    /** A token carrying one of these coins counts only when it is of this type and verified. */
+    readonly coinIds: readonly CoinId[];
+    /** Must change whenever the proofs this policy accepts change, a fix to its verification code included, so wallets check held tokens again. */
+    readonly revision?: string;
+}
 /** Mint-reason verifiers keyed by CBOR tag, registered at engine construction. */
 interface TokenPlugin {
     /** Stable identifier for diagnostics, e.g. `'bridge:tron-usdt'`. */
     readonly id: string;
     /** Mint-reason verifiers to register; a duplicate tag across plugins is INVALID_CONFIG. */
     readonly mintJustificationVerifiers?: readonly IMintJustificationVerifier[];
+    /** Issuance policies to register; a duplicate token type or coin across plugins is INVALID_CONFIG. */
+    readonly tokenIssuancePolicies?: readonly TokenIssuancePolicy[];
 }
 /** Plan an NFT mint (#785); `mintDataToken` then mints the plan. */
 interface BuildNftMintParams {
@@ -403,6 +414,8 @@ interface ITokenEngine {
      * read its bytes via `readTokenData`. (Used e.g. for on-chain invoice tokens.)
      */
     mintDataToken(params: MintDataTokenParams, options?: EngineOpOptions): Promise<SphereToken>;
+    /** Throws VALIDATION_ERROR when `mintDataToken` would refuse `params` before submitting, e.g. a reason tag no registered verifier handles. */
+    assertMintable(params: MintDataTokenParams): void;
     /** Plan an NFT mint: encode (and optionally sign as this engine's identity) the payload and derive its token id. No chain op. */
     buildNftMint(params: BuildNftMintParams): Promise<NftMintPlan>;
     /** Spend a token wholesale to a recipient pubkey; returns the recipient's finished token. */
@@ -508,7 +521,7 @@ interface EngineConfig {
      * terminate the pool.
      */
     readonly verification?: VerificationWorkerConfig;
-    /** Token plugins whose mint-reason verifiers join the engine's verification context. */
+    /** Token plugins whose mint-reason verifiers and issuance policies join the engine's verification context. */
     readonly plugins?: readonly TokenPlugin[];
 }
 /** Factory signature for the real adapter (implemented in Track A). */
@@ -571,7 +584,7 @@ declare function createSphereTokenEngine(config: EngineConfig): Promise<ITokenEn
  * }
  * ```
  */
-type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'TRANSFER_CONFLICT' | 'CERTIFICATION_UNCONFIRMED' | 'CHECKPOINT_PERSIST_FAILED' | 'SPLIT_CHECKPOINT_LOST' | 'CHECKPOINT_TRUSTBASE_MISMATCH' | 'STORAGE_ERROR' | 'SEND_SYNC_PENDING' | 'SEND_PARTIALLY_COMPLETED' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'INVALID_AMOUNT' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'PAYMENTS_NOT_COMPOSED' | 'SIGNING_ERROR' | 'SEND_QUEUE_TIMEOUT' | 'SEND_INSUFFICIENT_BALANCE' | 'SEND_RESERVATION_CANCELLED' | 'SEND_QUEUE_FULL' | 'MODULE_DESTROYED' | 'REENTRANT_GATE' | 'INVOICE_NO_TARGETS' | 'INVOICE_INVALID_ADDRESS' | 'INVOICE_NO_ASSETS' | 'INVOICE_INVALID_ASSET' | 'INVOICE_INVALID_AMOUNT' | 'INVOICE_INVALID_COIN' | 'INVOICE_INVALID_NFT' | 'INVOICE_PAST_DUE_DATE' | 'INVOICE_DUPLICATE_ADDRESS' | 'INVOICE_DUPLICATE_COIN' | 'INVOICE_DUPLICATE_NFT' | 'INVOICE_MINT_FAILED' | 'INVOICE_INVALID_PROOF' | 'INVOICE_WRONG_TOKEN_TYPE' | 'INVOICE_INVALID_DATA' | 'INVOICE_ALREADY_EXISTS' | 'INVOICE_NOT_FOUND' | 'INVOICE_NOT_TARGET' | 'INVOICE_ALREADY_CLOSED' | 'INVOICE_ALREADY_CANCELLED' | 'INVOICE_ORACLE_REQUIRED' | 'INVOICE_TERMINATED' | 'INVOICE_INVALID_TARGET' | 'INVOICE_INVALID_ASSET_INDEX' | 'INVOICE_RETURN_EXCEEDS_BALANCE' | 'INVOICE_INVALID_DELIVERY_METHOD' | 'INVOICE_INVALID_REFUND_ADDRESS' | 'INVOICE_INVALID_CONTACT' | 'INVOICE_INVALID_ID' | 'INVOICE_TOO_MANY_TARGETS' | 'INVOICE_TOO_MANY_ASSETS' | 'INVOICE_MEMO_TOO_LONG' | 'INVOICE_TERMS_TOO_LARGE' | 'INVOICE_NOT_TERMINATED' | 'INVOICE_NOT_CANCELLED' | 'INVOICE_STORAGE_FAILED' | 'RATE_LIMITED' | 'COMMUNICATIONS_UNAVAILABLE' | 'SWAP_INVALID_DEAL' | 'SWAP_INVALID_MANIFEST' | 'SWAP_NOT_FOUND' | 'SWAP_WRONG_STATE' | 'SWAP_RESOLVE_FAILED' | 'SWAP_DM_SEND_FAILED' | 'SWAP_ESCROW_REJECTED' | 'SWAP_DEPOSIT_FAILED' | 'SWAP_PAYOUT_VERIFICATION_FAILED' | 'SWAP_ALREADY_EXISTS' | 'SWAP_ALREADY_COMPLETED' | 'SWAP_ALREADY_CANCELLED' | 'SWAP_TIMEOUT' | 'SWAP_LIMIT_EXCEEDED' | 'SWAP_ALREADY_INITIALIZED' | 'SWAP_MODULE_DESTROYED' | 'SWAP_NOT_INITIALIZED';
+type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'TRANSFER_CONFLICT' | 'CERTIFICATION_UNCONFIRMED' | 'CHECKPOINT_PERSIST_FAILED' | 'SPLIT_CHECKPOINT_LOST' | 'CHECKPOINT_TRUSTBASE_MISMATCH' | 'MINT_REASON_UNVERIFIABLE' | 'STORAGE_ERROR' | 'SEND_SYNC_PENDING' | 'SEND_PARTIALLY_COMPLETED' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'INVALID_AMOUNT' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'PAYMENTS_NOT_COMPOSED' | 'SIGNING_ERROR' | 'SEND_QUEUE_TIMEOUT' | 'SEND_INSUFFICIENT_BALANCE' | 'SEND_RESERVATION_CANCELLED' | 'SEND_QUEUE_FULL' | 'MODULE_DESTROYED' | 'REENTRANT_GATE' | 'INVOICE_NO_TARGETS' | 'INVOICE_INVALID_ADDRESS' | 'INVOICE_NO_ASSETS' | 'INVOICE_INVALID_ASSET' | 'INVOICE_INVALID_AMOUNT' | 'INVOICE_INVALID_COIN' | 'INVOICE_INVALID_NFT' | 'INVOICE_PAST_DUE_DATE' | 'INVOICE_DUPLICATE_ADDRESS' | 'INVOICE_DUPLICATE_COIN' | 'INVOICE_DUPLICATE_NFT' | 'INVOICE_MINT_FAILED' | 'INVOICE_INVALID_PROOF' | 'INVOICE_WRONG_TOKEN_TYPE' | 'INVOICE_INVALID_DATA' | 'INVOICE_ALREADY_EXISTS' | 'INVOICE_NOT_FOUND' | 'INVOICE_NOT_TARGET' | 'INVOICE_ALREADY_CLOSED' | 'INVOICE_ALREADY_CANCELLED' | 'INVOICE_ORACLE_REQUIRED' | 'INVOICE_TERMINATED' | 'INVOICE_INVALID_TARGET' | 'INVOICE_INVALID_ASSET_INDEX' | 'INVOICE_RETURN_EXCEEDS_BALANCE' | 'INVOICE_INVALID_DELIVERY_METHOD' | 'INVOICE_INVALID_REFUND_ADDRESS' | 'INVOICE_INVALID_CONTACT' | 'INVOICE_INVALID_ID' | 'INVOICE_TOO_MANY_TARGETS' | 'INVOICE_TOO_MANY_ASSETS' | 'INVOICE_MEMO_TOO_LONG' | 'INVOICE_TERMS_TOO_LARGE' | 'INVOICE_NOT_TERMINATED' | 'INVOICE_NOT_CANCELLED' | 'INVOICE_STORAGE_FAILED' | 'RATE_LIMITED' | 'COMMUNICATIONS_UNAVAILABLE' | 'SWAP_INVALID_DEAL' | 'SWAP_INVALID_MANIFEST' | 'SWAP_NOT_FOUND' | 'SWAP_WRONG_STATE' | 'SWAP_RESOLVE_FAILED' | 'SWAP_DM_SEND_FAILED' | 'SWAP_ESCROW_REJECTED' | 'SWAP_DEPOSIT_FAILED' | 'SWAP_PAYOUT_VERIFICATION_FAILED' | 'SWAP_ALREADY_EXISTS' | 'SWAP_ALREADY_COMPLETED' | 'SWAP_ALREADY_CANCELLED' | 'SWAP_TIMEOUT' | 'SWAP_LIMIT_EXCEEDED' | 'SWAP_ALREADY_INITIALIZED' | 'SWAP_MODULE_DESTROYED' | 'SWAP_NOT_INITIALIZED';
 declare class SphereError extends Error {
     readonly code: SphereErrorCode;
     readonly cause?: unknown;
@@ -623,6 +636,10 @@ declare class TransferConflictError extends SphereError {
  * certified proof + recipient blob, or records the spend if a foreign tx won the
  * race — never a second on-chain spend (sdk-changes E.2/E.3, #631).
  */
+/** A token's mint reason cannot be judged yet: no verifier for its tag here, or the plugin could not reach an answer. */
+declare class MintReasonUnverifiableError extends SphereError {
+    constructor(message: string, cause?: unknown);
+}
 declare class ProofUnconfirmedError extends SphereError {
     readonly mayHaveCertified: true;
     constructor(message: string, cause?: unknown);
@@ -715,4 +732,4 @@ declare class SpherePaymentData implements IPaymentData {
  */
 declare function decodeSpherePaymentData(bytes: Uint8Array): Promise<IPaymentData>;
 
-export { type BuildNftMintParams, type BurnParams, CheckpointPersistFailedError, CheckpointTrustbaseMismatchError, type CoinId, type CreateTokenEngine, type EngineConfig, type EngineIdentity, type EngineOpOptions, type EngineVerifyResult, type ITokenEngine, type MintDataTokenParams, type MintParams, NFT_DOCUMENT_MEDIA_TYPE, NFT_FORMAT_VERSION, NFT_LINK_TAG, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintPlan, type NftReading, type NftSignatureContext, type NftSignatureStatus, type ParsedNft, ProofUnconfirmedError, type SphereAsset, type SphereNetwork, SpherePaymentData, type SphereToken, type SphereValue, SplitCheckpointLostError, type SplitCheckpointStore, type SplitOutput, type SplitParams, type SplitResult, type TokenBlob, type TokenPlugin, TransferConflictError, type TransferParams, type VerificationWorker, type VerificationWorkerConfig, createSphereTokenEngine, decodeSpherePaymentData, deriveDirectAddress, encodeNftContent, encodeNftSigned, isNftDocumentLink, nftSignedDigest, parseNftDocument, parseNftPayload, sphereAssetToSdk, verifyNftLinkContent, verifyNftSignature };
+export { type BuildNftMintParams, type BurnParams, CheckpointPersistFailedError, CheckpointTrustbaseMismatchError, type CoinId, type CreateTokenEngine, type EngineConfig, type EngineIdentity, type EngineOpOptions, type EngineVerifyResult, type ITokenEngine, type MintDataTokenParams, type MintParams, MintReasonUnverifiableError, NFT_DOCUMENT_MEDIA_TYPE, NFT_FORMAT_VERSION, NFT_LINK_TAG, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintPlan, type NftReading, type NftSignatureContext, type NftSignatureStatus, type ParsedNft, ProofUnconfirmedError, type SphereAsset, type SphereNetwork, SpherePaymentData, type SphereToken, type SphereValue, SplitCheckpointLostError, type SplitCheckpointStore, type SplitOutput, type SplitParams, type SplitResult, type TokenBlob, type TokenIssuancePolicy, type TokenPlugin, TransferConflictError, type TransferParams, type VerificationWorker, type VerificationWorkerConfig, createSphereTokenEngine, decodeSpherePaymentData, deriveDirectAddress, encodeNftContent, encodeNftSigned, isNftDocumentLink, nftSignedDigest, parseNftDocument, parseNftPayload, sphereAssetToSdk, verifyNftLinkContent, verifyNftSignature };

package/dist/token-engine/index.js

@@ -203,6 +203,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 = 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 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(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 === VerificationStatus.OK ? new VerificationResult(RULE, VerificationStatus.OK, "", [result]) : new VerificationResult(RULE, 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) {
@@ -723,45 +867,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: ${InclusionProofVerificationStatus.TRANSACTION_HASH_MISMATCH}`) {
@@ -1426,15 +1531,17 @@ async function readTokenNft(token) {
 }
 
 // token-engine/plugin-ops.ts
-function contextWithMintVerifiers(base, verifiers) {
-  const registry = new 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 VerificationContext(
-    base.trustBase,
-    base.predicateVerifier,
-    base.unicityCertificateVerifier,
-    registry,
-    new TokenIssuanceVerifierService(false)
+    deps.trustBase,
+    deps.predicateVerifier,
+    deps.unicityCertificateVerifier,
+    deps.mintJustificationVerifier.overlaid(verifiers),
+    deps.verificationContext.tokenIssuanceVerifier
   );
 }
 
@@ -1522,9 +1629,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([
   CertificationStatus.STATE_ID_MISMATCH,
@@ -1614,8 +1718,9 @@ var SphereTokenEngine = class {
     const token = await 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 = SignaturePredicate.create(params.recipientPubkey);
     const tokenType = params.tokenType ? new TokenType(params.tokenType) : TokenType.generate();
     const salt = params.salt ? TokenSalt.fromBytes(params.salt) : TokenSalt.generate();
@@ -1629,8 +1734,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 Token.mint(certified, verifiers ? contextWithMintVerifiers(this.deps, verifiers) : this.deps.verificationContext));
+    return wrapToken(await Token.mint(certified, context));
   }
   buildNftMint(params) {
     return planNftMint(this.deps, params);
@@ -1967,20 +2071,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 = 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",
@@ -2058,11 +2172,15 @@ async function createSphereTokenEngine(config) {
   const unicityCertificateVerifier = new UnicityCertificateVerifier(
     new UnicitySealQuorumSignaturesVerificationRule(new Secp256k1SignatureVerifier(), new VerifiedSealCache(256))
   );
-  const mintJustificationVerifier = new MintJustificationVerifierService();
+  const mintJustificationVerifier = new MintReasonRegistry();
   mintJustificationVerifier.register(
     new SplitMintJustificationVerifier(decodeSpherePaymentData)
   );
-  registerPluginVerifiers(mintJustificationVerifier, config.plugins);
+  const tokenIssuanceVerifier = new TokenIssuanceVerifierService(false);
+  registerPlugins(
+    { reasons: mintJustificationVerifier, policies: tokenIssuanceVerifier, claims: new CoinClaims() },
+    config.plugins
+  );
   const deps = {
     client: new StateTransitionClient(new AggregatorClient(config.aggregatorUrl, config.apiKey ?? null)),
     trustBase,
@@ -2074,7 +2192,7 @@ async function createSphereTokenEngine(config) {
       predicateVerifier,
       unicityCertificateVerifier,
       mintJustificationVerifier,
-      new TokenIssuanceVerifierService(false)
+      tokenIssuanceVerifier
     ),
     signingService: new SigningService(config.privateKey),
     // Also the HKDF ikm for deterministic realization (Part E.1) — the
@@ -2095,6 +2213,7 @@ async function createSphereTokenEngine(config) {
 export {
   CheckpointPersistFailedError,
   CheckpointTrustbaseMismatchError,
+  MintReasonUnverifiableError,
   NFT_DOCUMENT_MEDIA_TYPE,
   NFT_FORMAT_VERSION,
   NFT_LINK_TAG,