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

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

@@ -1,3 +1,5 @@
+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 { 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';
@@ -189,6 +191,23 @@ interface MintDataTokenParams {
     readonly tokenType?: Uint8Array;
     /** Salt bytes; deterministic salt → deterministic (terms-derived) tokenId. */
     readonly salt?: Uint8Array;
+    /** Genesis mint reason (the SDK's `justification`): tagged CBOR a registered verifier validates. */
+    readonly justification?: Uint8Array;
+    /** Verifiers for this mint's genesis reason, in place of the ones registered on the engine. */
+    readonly mintJustificationVerifiers?: readonly IMintJustificationVerifier[];
+}
+/** Spend a token to a burn predicate with the reason bytes as aux data. */
+interface BurnParams {
+    readonly token: SphereToken;
+    /** The recipient predicate is `BurnPredicate(sha256(reasonBytes))`; the bytes ride in the aux data. */
+    readonly reasonBytes: Uint8Array;
+}
+/** 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[];
 }
 /** Plan an NFT mint (#785); `mintDataToken` then mints the plan. */
 interface BuildNftMintParams {
@@ -365,6 +384,8 @@ interface ITokenEngine {
     readMemo(token: SphereToken): Uint8Array | null;
     /** Raw genesis data of a token (e.g. a data-token's terms). `null` when absent. Synchronous. */
     readTokenData(token: SphereToken): Uint8Array | null;
+    /** The genesis mint reason (`justification`) of a token; `null` when it was minted without one. Synchronous. */
+    readTokenJustification(token: SphereToken): Uint8Array | null;
     /** Read a token's genesis payload as an NFT. NEVER throws; null = not a recognised NFT. */
     readNft(token: SphereToken): Promise<NftReading | null>;
     /**
@@ -386,6 +407,8 @@ interface ITokenEngine {
     buildNftMint(params: BuildNftMintParams): Promise<NftMintPlan>;
     /** Spend a token wholesale to a recipient pubkey; returns the recipient's finished token. */
     transfer(params: TransferParams, options?: EngineOpOptions): Promise<SphereToken>;
+    /** Spend the token to `BurnPredicate(sha256(reasonBytes))` with the reason bytes as aux data. */
+    burn(params: BurnParams, options?: EngineOpOptions): Promise<SphereToken>;
     /** Split a token into N value-conserving outputs (burn source + internally mint each output). */
     split(params: SplitParams, options?: EngineOpOptions): Promise<SplitResult>;
     /** Fully verify a token against the trust base. */
@@ -485,6 +508,8 @@ interface EngineConfig {
      * terminate the pool.
      */
     readonly verification?: VerificationWorkerConfig;
+    /** Token plugins whose mint-reason verifiers join the engine's verification context. */
+    readonly plugins?: readonly TokenPlugin[];
 }
 /** Factory signature for the real adapter (implemented in Track A). */
 type CreateTokenEngine = (config: EngineConfig) => Promise<ITokenEngine>;
@@ -690,4 +715,4 @@ declare class SpherePaymentData implements IPaymentData {
  */
 declare function decodeSpherePaymentData(bytes: Uint8Array): Promise<IPaymentData>;
 
-export { type BuildNftMintParams, 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, 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, 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 };

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

@@ -1,3 +1,5 @@
+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 { 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';
@@ -189,6 +191,23 @@ interface MintDataTokenParams {
     readonly tokenType?: Uint8Array;
     /** Salt bytes; deterministic salt → deterministic (terms-derived) tokenId. */
     readonly salt?: Uint8Array;
+    /** Genesis mint reason (the SDK's `justification`): tagged CBOR a registered verifier validates. */
+    readonly justification?: Uint8Array;
+    /** Verifiers for this mint's genesis reason, in place of the ones registered on the engine. */
+    readonly mintJustificationVerifiers?: readonly IMintJustificationVerifier[];
+}
+/** Spend a token to a burn predicate with the reason bytes as aux data. */
+interface BurnParams {
+    readonly token: SphereToken;
+    /** The recipient predicate is `BurnPredicate(sha256(reasonBytes))`; the bytes ride in the aux data. */
+    readonly reasonBytes: Uint8Array;
+}
+/** 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[];
 }
 /** Plan an NFT mint (#785); `mintDataToken` then mints the plan. */
 interface BuildNftMintParams {
@@ -365,6 +384,8 @@ interface ITokenEngine {
     readMemo(token: SphereToken): Uint8Array | null;
     /** Raw genesis data of a token (e.g. a data-token's terms). `null` when absent. Synchronous. */
     readTokenData(token: SphereToken): Uint8Array | null;
+    /** The genesis mint reason (`justification`) of a token; `null` when it was minted without one. Synchronous. */
+    readTokenJustification(token: SphereToken): Uint8Array | null;
     /** Read a token's genesis payload as an NFT. NEVER throws; null = not a recognised NFT. */
     readNft(token: SphereToken): Promise<NftReading | null>;
     /**
@@ -386,6 +407,8 @@ interface ITokenEngine {
     buildNftMint(params: BuildNftMintParams): Promise<NftMintPlan>;
     /** Spend a token wholesale to a recipient pubkey; returns the recipient's finished token. */
     transfer(params: TransferParams, options?: EngineOpOptions): Promise<SphereToken>;
+    /** Spend the token to `BurnPredicate(sha256(reasonBytes))` with the reason bytes as aux data. */
+    burn(params: BurnParams, options?: EngineOpOptions): Promise<SphereToken>;
     /** Split a token into N value-conserving outputs (burn source + internally mint each output). */
     split(params: SplitParams, options?: EngineOpOptions): Promise<SplitResult>;
     /** Fully verify a token against the trust base. */
@@ -485,6 +508,8 @@ interface EngineConfig {
      * terminate the pool.
      */
     readonly verification?: VerificationWorkerConfig;
+    /** Token plugins whose mint-reason verifiers join the engine's verification context. */
+    readonly plugins?: readonly TokenPlugin[];
 }
 /** Factory signature for the real adapter (implemented in Track A). */
 type CreateTokenEngine = (config: EngineConfig) => Promise<ITokenEngine>;
@@ -690,4 +715,4 @@ declare class SpherePaymentData implements IPaymentData {
  */
 declare function decodeSpherePaymentData(bytes: Uint8Array): Promise<IPaymentData>;
 
-export { type BuildNftMintParams, 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, 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, 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 };