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

package/dist/core/index.d.ts

@@ -1,3 +1,4 @@
+import { IMintJustificationVerifier } from '@unicitylabs/state-transition-sdk/lib/transaction/verification/IMintJustificationVerifier.js';
 import { Token as Token$1 } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
 import { NostrClient, NostrKeyManager } from '@unicitylabs/nostr-js-sdk';
 
@@ -218,6 +219,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 {
@@ -290,134 +308,205 @@ interface NftReading {
     readonly signature: NftSignatureStatus;
 }
 
-interface SendRequest {
-    recipient: string;
-    amount: string;
-    coinId: string;
-    memo?: string;
-}
-interface SendWholeTokenRequest {
-    recipient: string;
-    tokenId: string;
-    memo?: string;
-}
-interface MintResult {
-    success: boolean;
-    tokenId?: string;
-    error?: string;
-}
-/** #785: `content` uses ERC-721 field names; `sign` (default true) signs as creator with this wallet's chain key. */
-interface MintNftRequest {
-    readonly content: NftContent;
-    readonly sign?: boolean;
-}
-interface NftView extends NftReading {
-    readonly tokenId: string;
-}
-interface HistoryEntry {
-    id: string;
-    type: 'SENT' | 'RECEIVED' | 'MINT';
-    coinId: string;
-    amount: string;
-    symbol?: string;
-    timestamp: number;
-    memo?: string;
-    transferId?: string;
-    tokenId?: string;
-    senderPubkey?: string;
-    senderNametag?: string;
-    recipientPubkey?: string;
-    recipientNametag?: string;
-    tokenIds?: {
-        id: string;
-        amount: string;
-    }[];
-}
-interface HistoryPage {
-    entries: HistoryEntry[];
-    more: boolean;
-    cursor: string | null;
+/**
+ * token-engine/engine.ts — the FROZEN public port (ITokenEngine) + its config.
+ *
+ * This is the contract both migration tracks build against. It is sphere-domain
+ * only (see types.ts). The granular, SDK-typed steps (buildMint, submit,
+ * awaitProof, certify, …) are an INTERNAL concern of the real adapter and are
+ * intentionally NOT part of this public interface.
+ */
+
+/**
+ * Durable, any-device store for a split's burn checkpoint (sdk-changes E.4, sphere-sdk#501
+ * option b). The engine passes opaque PLAINTEXT bytes; a transport adapter (the wallet-api
+ * provider) is responsible for AAD-encryption and the wallet-api §16 intent-progress round-trip.
+ *
+ * The store is the resume seed for the one split input the engine cannot re-derive — the burn's
+ * aggregator-issued inclusion proof — so the mint justification is rebuilt from stored bytes, not
+ * a refetch (the aggregator regenerates proofs per request).
+ */
+interface SplitCheckpointStore {
+    /**
+     * Insert-once, first-write-wins. MUST resolve only AFTER the store acked durability, and MUST
+     * resolve with the AUTHORITATIVE stored bytes — the caller's own on a fresh write, or the FIRST
+     * writer's when the slot `(transferId, opIndex)` was already taken (the caller adopts those and
+     * mints from them, so concurrent resumers converge on one burn proof).
+     */
+    put(transferId: string, opIndex: number, bytes: Uint8Array): Promise<Uint8Array>;
+    /** The stored bytes for the slot, or `null` when none exists. */
+    get(transferId: string, opIndex: number): Promise<Uint8Array | null>;
 }
-type PaymentRequestStatus = 'pending' | 'settling' | 'paid' | 'rejected' | 'expired';
-interface PaymentRequestView {
-    id: string;
-    requestId: string;
-    senderPubkey: string;
-    senderNametag?: string;
-    amount: string;
-    coinId: string;
-    symbol?: string;
-    message?: string;
-    timestamp: number;
-    status: PaymentRequestStatus;
+/** Options common to the long-running, network-bound operations. */
+interface EngineOpOptions {
+    /** Cancels the operation (including inclusion-proof polling). */
+    readonly signal?: AbortSignal;
+    /**
+     * Durable burn-checkpoint store for a resumable split (sdk-changes E.4, sphere-sdk#501). When
+     * present, `split()` persists the burn's certified proof AND awaits its durable ack BEFORE
+     * submitting any mint leg, and rebuilds the mint justification from the stored bytes on resume —
+     * so a split resumed after any mint leg certified recovers instead of stranding its outputs.
+     *
+     * Absent keeps today's behavior (a fresh burn proof per attempt): fine for a mid-split resume
+     * with no mint yet certified, but a split resumed AFTER a mint certified cannot recover — a
+     * documented residual for fully-local compositions; the live path MUST supply the store.
+     */
+    readonly checkpointStore?: SplitCheckpointStore;
+    /**
+     * Realization seed for deterministic transfer/split (Part E, sdk-changes E.1/E.3):
+     * a client-generated UUIDv4 in canonical lowercase string form. Every value the
+     * transaction binds to (stateMask, per-output salts) is HKDF-derived from the
+     * wallet key + this id, so re-calling the op with the same `transferId` and
+     * inputs rebuilds the byte-identical transaction and resumes an interrupted
+     * attempt instead of losing funds. Persist it BEFORE calling the engine.
+     *
+     * If absent, the engine generates one internally (`crypto.randomUUID()`) — the
+     * derivation path is identical, but the call is NOT resumable (the seed is
+     * gone if the process dies mid-op).
+     */
+    readonly transferId?: string;
+    /**
+     * Ordinal of this engine op WITHIN one logical send sharing a `transferId`
+     * (ARCHITECTURE §7: D whole-token transfers + at most one split under ONE
+     * intent). It indexes the op-level HKDF derivations (`stateMask`, the split
+     * `burn` mask) so distinct ops never reuse a mask — §8.1's "per-transfer
+     * unique". Per-output split salts are indexed by output ordinal in their own
+     * `salt` field domain; callers MUST NOT run two splits under one transferId.
+     * Default 0 (single-op sends). Resume MUST replay the same (transferId,
+     * opIndex) pairing per source.
+     */
+    readonly opIndex?: number;
 }
-interface PaymentsRequestsApi {
-    create(to: string, terms: {
-        coinId: string;
-        amount: string;
-        memo?: string;
-    }): Promise<{
-        success: boolean;
-        requestId?: string;
-        error?: string;
+/**
+ * The token engine port. The wallet's secp256k1 identity, the target network,
+ * the aggregator client and the trust base are all bound at construction
+ * (see EngineConfig); operations below take only sphere-domain arguments.
+ */
+interface ITokenEngine {
+    /** This engine's wallet identity (chain pubkey). Synchronous. */
+    getIdentity(): EngineIdentity;
+    /**
+     * Legacy `DIRECT://` address for the given pubkey (defaults to this engine's
+     * identity). This is the ONLY "address" in v2 and is kept stable across the
+     * migration (Path A) so Quest XP / Unicity IDs keyed on it survive. Async —
+     * the derivation hashes via the SDK.
+     */
+    deriveIdentityAddress(pubkey?: Uint8Array): Promise<string>;
+    /**
+     * Genesis-stable token id — 64-char lowercase hex of the v2 TokenId (same
+     * across every state). Use for dedup / history / tombstone keys. Synchronous.
+     */
+    tokenId(token: SphereToken): string;
+    /** Decoded value of a token (cached). Synchronous. */
+    readValue(token: SphereToken): SphereValue | null;
+    /** Balance of a single coin within a token. Synchronous. */
+    balanceOf(token: SphereToken, coinId: CoinId): bigint;
+    /**
+     * The opaque on-chain memo delivered with this token: the latest transfer's
+     * data for a transferred token, else the memo in a minted output's value
+     * envelope (split). Returns `null` when there is no memo — including for data
+     * tokens (no value envelope; use `readTokenData`) and memo-less value tokens.
+     * To tell a data token from a value token, check `readValue` (null ⇒
+     * data/value-less token). Synchronous.
+     */
+    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>;
+    /**
+     * Mint (issue) a new token to a recipient pubkey. NOT a wallet end-user flow —
+     * this is the issuer/developer capability: an app issuing its own tokens
+     * (rewards, in-app currency, tickets) to users, or seeding test balances. v2
+     * makes standalone mint first-class (Token.mint accepts a genesis with a null
+     * justification). Split's per-output mint is a separate, internal path; the
+     * Unicity-ID/nametag mint is a distinct identity surface (see migration plan §4.4).
+     */
+    mint(params: MintParams, options?: EngineOpOptions): Promise<SphereToken>;
+    /**
+     * Mint a NON-value (data) token: opaque `data` + custom `tokenType` + deterministic
+     * `salt` → a stable, terms-derived `tokenId`. The result has `value === null`;
+     * read its bytes via `readTokenData`. (Used e.g. for on-chain invoice tokens.)
+     */
+    mintDataToken(params: MintDataTokenParams, options?: EngineOpOptions): Promise<SphereToken>;
+    /** 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. */
+    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. */
+    verify(token: SphereToken, options?: EngineOpOptions): Promise<EngineVerifyResult>;
+    /** Whether the token's current state has already been spent on the network. */
+    isSpent(token: SphereToken, options?: EngineOpOptions): Promise<boolean>;
+    /**
+     * Whether the token's CURRENT state is locked to `SignaturePredicate(pubkey)`.
+     * Local + synchronous (predicate byte-compare, no network). The receive path
+     * uses it to reject tokens that are not actually addressed to this wallet.
+     */
+    isOwnedBy(token: SphereToken, pubkey: Uint8Array): boolean;
+    /** Serialize a token for storage/transport. Synchronous. */
+    encodeToken(token: SphereToken): TokenBlob;
+    /** Reconstruct a token from its blob (decodes embedded payment data). */
+    decodeToken(blob: TokenBlob): Promise<SphereToken>;
+    /**
+     * The backend-true delivery keys for encoded TokenBlob bytes: the
+     * genesis-stable tokenId and the SDK's PROTOCOL state hash of the latest
+     * state (DataHash imprint, hex). wallet-api keys mailbox entries on exactly
+     * this pair (entry_id = SHA-256(tokenId ‖ stateHash); §8.2 step 4 validates
+     * a deposit's claimed stateHash against it) — a plain hash over the token
+     * bytes is NOT this value and 422s on deposit. Delivery implementations MUST
+     * derive their ids through this method, never locally.
+     */
+    deliveryKeys(blobBytes: Uint8Array): Promise<{
+        tokenId: string;
+        stateHash: string;
     }>;
-    list(): PaymentRequestView[];
-    pay(id: string): Promise<TransferResult>;
-    decline(id: string): Promise<void>;
-    dismissProcessed(): void;
+    /**
+     * Release engine-owned OS resources — today only the verification worker pool.
+     * Idempotent; optional because an engine owning none need not define it.
+     */
+    dispose?(): void;
 }
 /**
- * A pending-transfers row, derived ON READ from the §6 stores (intent backstop
- * + delivery journal + shortfalls) — never a cached mirror. kind 'shortfall' =
- * a completed partial (#690) whose `amount` is the remainder still owed;
- * legs.certified counts journaled legs (certified, delivery still owed).
+ * Engine construction config. Sphere-domain inputs only: the factory maps
+ * `network` → SDK NetworkId, builds the aggregator client from `aggregatorUrl`,
+ * the signing service from `privateKey`, and loads the trust base internally.
+ *
+ * NOTE: trust-base sourcing + proof-policy defaults are finalized in Phase 0.8;
+ * this shape may gain fields there without affecting the ITokenEngine contract.
  */
-interface PendingTransfer {
-    transferId: string;
-    kind: 'open' | 'shortfall';
-    recipient: string;
-    coinId: string;
-    amount: string;
-    /** Set instead of coinId/amount when the intent is a token-addressed spend. */
-    tokenId?: string;
-    legs: {
-        certified: number;
-        total: number;
-    };
-    deliveryPending: boolean;
-    createdAt: number;
+/**
+ * The web-`Worker` subset the verification pool drives (in Node wrap a `worker_threads.Worker`).
+ * A browser `Worker` has these members, but under `strictFunctionTypes` its `ErrorEvent` /
+ * `MessageEvent` handler types are not assignable here (TS2322), so it needs a cast or a thin
+ * wrapper. Payloads stay `unknown` so no base-SDK wire type reaches this port.
+ */
+interface VerificationWorker {
+    onerror: ((event: {
+        message: string;
+    }) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    postMessage(message: unknown): void;
+    terminate(): void;
 }
-type ConnectionStatus$1 = 'connected' | 'degraded' | 'offline';
-interface PaymentsV2 {
-    prewarmSend(request: SendRequest): Promise<void>;
-    discardPrewarm(): void;
-    assets(coinId?: string): Promise<Asset[]>;
-    tokens(filter?: {
-        coinId?: string;
-    }): Token[];
-    coinless(): CoinlessToken[];
-    tokenData(tokenId: string): Promise<Uint8Array | null>;
-    /** One held token read as an NFT; null = its payload is not a recognised NFT. `creator` is only CLAIMED unless `signature` is 'valid'. Throws VALIDATION_ERROR when not held, STORAGE_ERROR when its blob is missing (same contract as tokenData). */
-    nft(tokenId: string): Promise<NftView | null>;
-    /** Batch read for list views. Ids not held, blobs missing or undecodable, and non-NFT payloads are simply absent from the map. Throws only on a transport failure. */
-    nfts(tokenIds: readonly string[]): Promise<ReadonlyMap<string, NftView>>;
-    history(page?: {
-        before?: string;
-        limit?: number;
-    }): Promise<HistoryPage>;
-    send(req: SendRequest): Promise<TransferResult>;
-    sendWholeToken(req: SendWholeTokenRequest): Promise<TransferResult>;
-    /** NFT-scoped twin: refuses a valued source. Connect's `send_nft` routes here. */
-    sendCoinless(req: SendWholeTokenRequest): Promise<TransferResult>;
-    mint(coinId: string, amount: bigint): Promise<MintResult>;
-    mintNft(request: MintNftRequest): Promise<MintResult>;
-    receive(): Promise<{
-        transfers: IncomingTransfer[];
-    }>;
-    pendingTransfers(): Promise<PendingTransfer[]>;
-    resumeNow(): Promise<void>;
-    connectionStatus(): ConnectionStatus$1;
-    readonly requests: PaymentsRequestsApi;
+/**
+ * Opt-in PARALLEL token verification (state-transition-sdk 2.0.2+): per-transfer
+ * work fans out to a worker pool instead of walking the calling thread. You
+ * author and bundle the entry script, and its predicate verifier MUST match the
+ * engine's or the verdict silently diverges — docs/VERIFICATION-WORKERS.md.
+ */
+interface VerificationWorkerConfig {
+    /** Spawn ONE worker running that entry script. Called lazily, up to `poolSize` times. */
+    readonly createWorker: () => VerificationWorker;
+    /** Maximum workers in the pool (default 4). Workers are reused across verify() calls. */
+    readonly poolSize?: number;
 }
 
 /**
@@ -523,9 +612,179 @@ declare class PartialSendConflictError extends SphereError {
  */
 declare function isPossiblyCommittedSendOutcome(err: unknown): boolean;
 /**
- * Type guard to check if an error is a SphereError
+ * Type guard to check if an error is a SphereError
+ */
+declare function isSphereError(err: unknown): err is SphereError;
+
+interface SendRequest {
+    recipient: string;
+    amount: string;
+    coinId: string;
+    memo?: string;
+}
+interface SendWholeTokenRequest {
+    recipient: string;
+    tokenId: string;
+    memo?: string;
+}
+interface MintResult {
+    success: boolean;
+    tokenId?: string;
+    error?: string;
+}
+/** Custom-genesis mint (a TokenPlugin's token), always to this wallet; `assets` = what the payload declares. */
+interface MintCustomRequest {
+    readonly tokenType: Uint8Array;
+    readonly salt: Uint8Array;
+    readonly data: Uint8Array;
+    readonly justification?: Uint8Array;
+    readonly assets: readonly {
+        coinId: string;
+        amount: bigint;
+    }[];
+    readonly mintJustificationVerifiers?: readonly IMintJustificationVerifier[];
+}
+/** Burn a held token to `BurnPredicate(sha256(reasonBytes))` with the bytes as aux data. */
+interface BurnRequest {
+    readonly tokenId: string;
+    readonly reasonBytes: Uint8Array;
+}
+interface BurnResult {
+    success: boolean;
+    burnId: string;
+    tokenId: string;
+    /** The burned blob, the proof of the burn: persist it, then `acknowledgeBurn(burnId)`. */
+    burnedToken?: Uint8Array;
+    error?: string;
+}
+/** A burn not yet acknowledged: in flight (`burnedToken` null), certified, or settled. */
+interface PendingBurn {
+    readonly burnId: string;
+    readonly tokenId: string;
+    readonly reasonBytes: Uint8Array;
+    readonly burnedToken: Uint8Array | null;
+    readonly settled: boolean;
+    readonly createdAt: number;
+}
+/** #785: `content` uses ERC-721 field names; `sign` (default true) signs as creator with this wallet's chain key. */
+interface MintNftRequest {
+    readonly content: NftContent;
+    readonly sign?: boolean;
+}
+interface NftView extends NftReading {
+    readonly tokenId: string;
+}
+interface HistoryEntry {
+    id: string;
+    type: 'SENT' | 'RECEIVED' | 'MINT';
+    coinId: string;
+    amount: string;
+    symbol?: string;
+    timestamp: number;
+    memo?: string;
+    transferId?: string;
+    tokenId?: string;
+    senderPubkey?: string;
+    senderNametag?: string;
+    recipientPubkey?: string;
+    recipientNametag?: string;
+    tokenIds?: {
+        id: string;
+        amount: string;
+    }[];
+}
+interface HistoryPage {
+    entries: HistoryEntry[];
+    more: boolean;
+    cursor: string | null;
+}
+type PaymentRequestStatus = 'pending' | 'settling' | 'paid' | 'rejected' | 'expired';
+interface PaymentRequestView {
+    id: string;
+    requestId: string;
+    senderPubkey: string;
+    senderNametag?: string;
+    amount: string;
+    coinId: string;
+    symbol?: string;
+    message?: string;
+    timestamp: number;
+    status: PaymentRequestStatus;
+}
+interface PaymentsRequestsApi {
+    create(to: string, terms: {
+        coinId: string;
+        amount: string;
+        memo?: string;
+    }): Promise<{
+        success: boolean;
+        requestId?: string;
+        error?: string;
+    }>;
+    list(): PaymentRequestView[];
+    pay(id: string): Promise<TransferResult>;
+    decline(id: string): Promise<void>;
+    dismissProcessed(): void;
+}
+/**
+ * A pending-transfers row, derived ON READ from the §6 stores (intent backstop
+ * + delivery journal + shortfalls) — never a cached mirror. kind 'shortfall' =
+ * a completed partial (#690) whose `amount` is the remainder still owed;
+ * legs.certified counts journaled legs (certified, delivery still owed).
  */
-declare function isSphereError(err: unknown): err is SphereError;
+interface PendingTransfer {
+    transferId: string;
+    kind: 'open' | 'shortfall';
+    recipient: string;
+    coinId: string;
+    amount: string;
+    /** Set instead of coinId/amount when the intent is a token-addressed spend. */
+    tokenId?: string;
+    legs: {
+        certified: number;
+        total: number;
+    };
+    deliveryPending: boolean;
+    createdAt: number;
+}
+type ConnectionStatus$1 = 'connected' | 'degraded' | 'offline';
+interface PaymentsV2 {
+    prewarmSend(request: SendRequest): Promise<void>;
+    discardPrewarm(): void;
+    assets(coinId?: string): Promise<Asset[]>;
+    tokens(filter?: {
+        coinId?: string;
+    }): Token[];
+    coinless(): CoinlessToken[];
+    tokenData(tokenId: string): Promise<Uint8Array | null>;
+    /** The genesis mint reason of one held token; null when it was minted without one. Same contract as tokenData. */
+    tokenJustification(tokenId: string): Promise<Uint8Array | null>;
+    /** One held token read as an NFT; null = its payload is not a recognised NFT. `creator` is only CLAIMED unless `signature` is 'valid'. Throws VALIDATION_ERROR when not held, STORAGE_ERROR when its blob is missing (same contract as tokenData). */
+    nft(tokenId: string): Promise<NftView | null>;
+    /** Batch read for list views. Ids not held, blobs missing or undecodable, and non-NFT payloads are simply absent from the map. Throws only on a transport failure. */
+    nfts(tokenIds: readonly string[]): Promise<ReadonlyMap<string, NftView>>;
+    history(page?: {
+        before?: string;
+        limit?: number;
+    }): Promise<HistoryPage>;
+    send(req: SendRequest): Promise<TransferResult>;
+    sendWholeToken(req: SendWholeTokenRequest): Promise<TransferResult>;
+    /** NFT-scoped twin: refuses a valued source. Connect's `send_nft` routes here. */
+    sendCoinless(req: SendWholeTokenRequest): Promise<TransferResult>;
+    mint(coinId: string, amount: bigint): Promise<MintResult>;
+    mintNft(request: MintNftRequest): Promise<MintResult>;
+    mintCustom(request: MintCustomRequest): Promise<MintResult>;
+    burn(request: BurnRequest): Promise<BurnResult>;
+    pendingBurns(): Promise<PendingBurn[]>;
+    acknowledgeBurn(burnId: string): Promise<void>;
+    receive(): Promise<{
+        transfers: IncomingTransfer[];
+    }>;
+    pendingTransfers(): Promise<PendingTransfer[]>;
+    resumeNow(): Promise<void>;
+    connectionStatus(): ConnectionStatus$1;
+    readonly requests: PaymentsRequestsApi;
+}
 
 /**
  * Cryptographic utilities for SDK2
@@ -2566,203 +2825,6 @@ interface DerivedAddressInfo {
  */
 declare function discoverAddressesImpl(deriveTransportPubkey: (index: number) => DerivedAddressInfo, batchResolve: (transportPubkeys: string[]) => Promise<PeerInfo[]>, options?: DiscoverAddressesOptions): Promise<DiscoverAddressesResult>;
 
-/**
- * token-engine/engine.ts — the FROZEN public port (ITokenEngine) + its config.
- *
- * This is the contract both migration tracks build against. It is sphere-domain
- * only (see types.ts). The granular, SDK-typed steps (buildMint, submit,
- * awaitProof, certify, …) are an INTERNAL concern of the real adapter and are
- * intentionally NOT part of this public interface.
- */
-
-/**
- * Durable, any-device store for a split's burn checkpoint (sdk-changes E.4, sphere-sdk#501
- * option b). The engine passes opaque PLAINTEXT bytes; a transport adapter (the wallet-api
- * provider) is responsible for AAD-encryption and the wallet-api §16 intent-progress round-trip.
- *
- * The store is the resume seed for the one split input the engine cannot re-derive — the burn's
- * aggregator-issued inclusion proof — so the mint justification is rebuilt from stored bytes, not
- * a refetch (the aggregator regenerates proofs per request).
- */
-interface SplitCheckpointStore {
-    /**
-     * Insert-once, first-write-wins. MUST resolve only AFTER the store acked durability, and MUST
-     * resolve with the AUTHORITATIVE stored bytes — the caller's own on a fresh write, or the FIRST
-     * writer's when the slot `(transferId, opIndex)` was already taken (the caller adopts those and
-     * mints from them, so concurrent resumers converge on one burn proof).
-     */
-    put(transferId: string, opIndex: number, bytes: Uint8Array): Promise<Uint8Array>;
-    /** The stored bytes for the slot, or `null` when none exists. */
-    get(transferId: string, opIndex: number): Promise<Uint8Array | null>;
-}
-/** Options common to the long-running, network-bound operations. */
-interface EngineOpOptions {
-    /** Cancels the operation (including inclusion-proof polling). */
-    readonly signal?: AbortSignal;
-    /**
-     * Durable burn-checkpoint store for a resumable split (sdk-changes E.4, sphere-sdk#501). When
-     * present, `split()` persists the burn's certified proof AND awaits its durable ack BEFORE
-     * submitting any mint leg, and rebuilds the mint justification from the stored bytes on resume —
-     * so a split resumed after any mint leg certified recovers instead of stranding its outputs.
-     *
-     * Absent keeps today's behavior (a fresh burn proof per attempt): fine for a mid-split resume
-     * with no mint yet certified, but a split resumed AFTER a mint certified cannot recover — a
-     * documented residual for fully-local compositions; the live path MUST supply the store.
-     */
-    readonly checkpointStore?: SplitCheckpointStore;
-    /**
-     * Realization seed for deterministic transfer/split (Part E, sdk-changes E.1/E.3):
-     * a client-generated UUIDv4 in canonical lowercase string form. Every value the
-     * transaction binds to (stateMask, per-output salts) is HKDF-derived from the
-     * wallet key + this id, so re-calling the op with the same `transferId` and
-     * inputs rebuilds the byte-identical transaction and resumes an interrupted
-     * attempt instead of losing funds. Persist it BEFORE calling the engine.
-     *
-     * If absent, the engine generates one internally (`crypto.randomUUID()`) — the
-     * derivation path is identical, but the call is NOT resumable (the seed is
-     * gone if the process dies mid-op).
-     */
-    readonly transferId?: string;
-    /**
-     * Ordinal of this engine op WITHIN one logical send sharing a `transferId`
-     * (ARCHITECTURE §7: D whole-token transfers + at most one split under ONE
-     * intent). It indexes the op-level HKDF derivations (`stateMask`, the split
-     * `burn` mask) so distinct ops never reuse a mask — §8.1's "per-transfer
-     * unique". Per-output split salts are indexed by output ordinal in their own
-     * `salt` field domain; callers MUST NOT run two splits under one transferId.
-     * Default 0 (single-op sends). Resume MUST replay the same (transferId,
-     * opIndex) pairing per source.
-     */
-    readonly opIndex?: number;
-}
-/**
- * The token engine port. The wallet's secp256k1 identity, the target network,
- * the aggregator client and the trust base are all bound at construction
- * (see EngineConfig); operations below take only sphere-domain arguments.
- */
-interface ITokenEngine {
-    /** This engine's wallet identity (chain pubkey). Synchronous. */
-    getIdentity(): EngineIdentity;
-    /**
-     * Legacy `DIRECT://` address for the given pubkey (defaults to this engine's
-     * identity). This is the ONLY "address" in v2 and is kept stable across the
-     * migration (Path A) so Quest XP / Unicity IDs keyed on it survive. Async —
-     * the derivation hashes via the SDK.
-     */
-    deriveIdentityAddress(pubkey?: Uint8Array): Promise<string>;
-    /**
-     * Genesis-stable token id — 64-char lowercase hex of the v2 TokenId (same
-     * across every state). Use for dedup / history / tombstone keys. Synchronous.
-     */
-    tokenId(token: SphereToken): string;
-    /** Decoded value of a token (cached). Synchronous. */
-    readValue(token: SphereToken): SphereValue | null;
-    /** Balance of a single coin within a token. Synchronous. */
-    balanceOf(token: SphereToken, coinId: CoinId): bigint;
-    /**
-     * The opaque on-chain memo delivered with this token: the latest transfer's
-     * data for a transferred token, else the memo in a minted output's value
-     * envelope (split). Returns `null` when there is no memo — including for data
-     * tokens (no value envelope; use `readTokenData`) and memo-less value tokens.
-     * To tell a data token from a value token, check `readValue` (null ⇒
-     * data/value-less token). Synchronous.
-     */
-    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;
-    /** Read a token's genesis payload as an NFT. NEVER throws; null = not a recognised NFT. */
-    readNft(token: SphereToken): Promise<NftReading | null>;
-    /**
-     * Mint (issue) a new token to a recipient pubkey. NOT a wallet end-user flow —
-     * this is the issuer/developer capability: an app issuing its own tokens
-     * (rewards, in-app currency, tickets) to users, or seeding test balances. v2
-     * makes standalone mint first-class (Token.mint accepts a genesis with a null
-     * justification). Split's per-output mint is a separate, internal path; the
-     * Unicity-ID/nametag mint is a distinct identity surface (see migration plan §4.4).
-     */
-    mint(params: MintParams, options?: EngineOpOptions): Promise<SphereToken>;
-    /**
-     * Mint a NON-value (data) token: opaque `data` + custom `tokenType` + deterministic
-     * `salt` → a stable, terms-derived `tokenId`. The result has `value === null`;
-     * read its bytes via `readTokenData`. (Used e.g. for on-chain invoice tokens.)
-     */
-    mintDataToken(params: MintDataTokenParams, options?: EngineOpOptions): Promise<SphereToken>;
-    /** 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. */
-    transfer(params: TransferParams, 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. */
-    verify(token: SphereToken, options?: EngineOpOptions): Promise<EngineVerifyResult>;
-    /** Whether the token's current state has already been spent on the network. */
-    isSpent(token: SphereToken, options?: EngineOpOptions): Promise<boolean>;
-    /**
-     * Whether the token's CURRENT state is locked to `SignaturePredicate(pubkey)`.
-     * Local + synchronous (predicate byte-compare, no network). The receive path
-     * uses it to reject tokens that are not actually addressed to this wallet.
-     */
-    isOwnedBy(token: SphereToken, pubkey: Uint8Array): boolean;
-    /** Serialize a token for storage/transport. Synchronous. */
-    encodeToken(token: SphereToken): TokenBlob;
-    /** Reconstruct a token from its blob (decodes embedded payment data). */
-    decodeToken(blob: TokenBlob): Promise<SphereToken>;
-    /**
-     * The backend-true delivery keys for encoded TokenBlob bytes: the
-     * genesis-stable tokenId and the SDK's PROTOCOL state hash of the latest
-     * state (DataHash imprint, hex). wallet-api keys mailbox entries on exactly
-     * this pair (entry_id = SHA-256(tokenId ‖ stateHash); §8.2 step 4 validates
-     * a deposit's claimed stateHash against it) — a plain hash over the token
-     * bytes is NOT this value and 422s on deposit. Delivery implementations MUST
-     * derive their ids through this method, never locally.
-     */
-    deliveryKeys(blobBytes: Uint8Array): Promise<{
-        tokenId: string;
-        stateHash: string;
-    }>;
-    /**
-     * Release engine-owned OS resources — today only the verification worker pool.
-     * Idempotent; optional because an engine owning none need not define it.
-     */
-    dispose?(): void;
-}
-/**
- * Engine construction config. Sphere-domain inputs only: the factory maps
- * `network` → SDK NetworkId, builds the aggregator client from `aggregatorUrl`,
- * the signing service from `privateKey`, and loads the trust base internally.
- *
- * NOTE: trust-base sourcing + proof-policy defaults are finalized in Phase 0.8;
- * this shape may gain fields there without affecting the ITokenEngine contract.
- */
-/**
- * The web-`Worker` subset the verification pool drives (in Node wrap a `worker_threads.Worker`).
- * A browser `Worker` has these members, but under `strictFunctionTypes` its `ErrorEvent` /
- * `MessageEvent` handler types are not assignable here (TS2322), so it needs a cast or a thin
- * wrapper. Payloads stay `unknown` so no base-SDK wire type reaches this port.
- */
-interface VerificationWorker {
-    onerror: ((event: {
-        message: string;
-    }) => void) | null;
-    onmessage: ((event: {
-        data: unknown;
-    }) => void) | null;
-    postMessage(message: unknown): void;
-    terminate(): void;
-}
-/**
- * Opt-in PARALLEL token verification (state-transition-sdk 2.0.2+): per-transfer
- * work fans out to a worker pool instead of walking the calling thread. You
- * author and bundle the entry script, and its predicate verifier MUST match the
- * engine's or the verdict silently diverges — docs/VERIFICATION-WORKERS.md.
- */
-interface VerificationWorkerConfig {
-    /** Spawn ONE worker running that entry script. Called lazily, up to `poolSize` times. */
-    readonly createWorker: () => VerificationWorker;
-    /** Maximum workers in the pool (default 4). Workers are reused across verify() calls. */
-    readonly poolSize?: number;
-}
-
 interface ScopedKV {
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, value: T): Promise<void>;
@@ -3316,6 +3378,8 @@ interface SphereCreateOptions extends SphereWalletApiOptions {
      * {@link SphereInitOptions.verification}. Omit for the sequential verifier.
      */
     verification?: VerificationWorkerConfig;
+    /** Token plugins: mint-reason verifiers registered into every engine this Sphere builds. */
+    plugins?: readonly TokenPlugin[];
 }
 /** Options for loading existing wallet */
 interface SphereLoadOptions extends SphereWalletApiOptions {
@@ -3359,6 +3423,8 @@ interface SphereLoadOptions extends SphereWalletApiOptions {
      * {@link SphereInitOptions.verification}. Omit for the sequential verifier.
      */
     verification?: VerificationWorkerConfig;
+    /** Token plugins: mint-reason verifiers registered into every engine this Sphere builds. */
+    plugins?: readonly TokenPlugin[];
 }
 /** Options for importing a wallet */
 interface SphereImportOptions extends SphereWalletApiOptions {
@@ -3432,6 +3498,8 @@ interface SphereImportOptions extends SphereWalletApiOptions {
      * registration) still rejects, and the erased wallet is not restored: keep a backup of it.
      */
     overwrite?: boolean;
+    /** Token plugins: mint-reason verifiers registered into every engine this Sphere builds. */
+    plugins?: readonly TokenPlugin[];
 }
 /** Options for unified init (auto-create or load) */
 interface SphereInitOptions extends SphereWalletApiOptions {
@@ -3501,6 +3569,8 @@ interface SphereInitOptions extends SphereWalletApiOptions {
      * {@link VerificationWorkerConfig}); `sphere.destroy()` terminates the pool.
      */
     verification?: VerificationWorkerConfig;
+    /** Token plugins: mint-reason verifiers registered into every engine this Sphere builds. */
+    plugins?: readonly TokenPlugin[];
 }
 /** Result of init operation */
 interface SphereInitResult {
@@ -3605,6 +3675,8 @@ declare class Sphere {
      * the rebuild after an api-key change share one pool configuration.
      */
     private _verification;
+    /** Token plugins (SphereInitOptions.plugins), applied to every engine like _verification. */
+    private _plugins;
     /** This Sphere's OWN token registry. Disposed by destroy(); never the process global. */
     private _registry;
     private eventHandlers;