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

package/dist/modules/payments-v2/index.d.cts

@@ -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';
 
 declare const NFT_METADATA_TAG = 39052n;
@@ -173,6 +174,16 @@ 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;
 }
 /** Plan an NFT mint (#785); `mintDataToken` then mints the plan. */
 interface BuildNftMintParams {
@@ -245,6 +256,171 @@ interface NftReading {
     readonly signature: NftSignatureStatus;
 }
 
+/**
+ * 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;
+    /** 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;
+    }>;
+    /**
+     * Release engine-owned OS resources — today only the verification worker pool.
+     * Idempotent; optional because an engine owning none need not define it.
+     */
+    dispose?(): void;
+}
+
 /**
  * SDK2 Core Types
  * Platform-independent type definitions
@@ -434,6 +610,40 @@ interface MintResult {
     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;
@@ -525,6 +735,8 @@ interface PaymentsV2 {
     }): 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. */
@@ -539,6 +751,10 @@ interface PaymentsV2 {
     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[];
     }>;
@@ -806,6 +1022,31 @@ interface NftMintJournalEntry {
     tokenTypeHex: string;
     createdAt: number;
 }
+interface CustomMintJournalEntry {
+    mintId: string;
+    tokenId: string;
+    dataHex: string;
+    saltHex: string;
+    tokenTypeHex: string;
+    justificationHex: string | null;
+    assets: {
+        coinId: string;
+        amount: string;
+    }[];
+    createdAt: number;
+}
+interface BurnJournalEntry {
+    burnId: string;
+    tokenId: string;
+    reasonHex: string;
+    burnedTokenHex: string | null;
+    settled: boolean;
+    assets: {
+        coinId: string;
+        amount: string;
+    }[];
+    createdAt: number;
+}
 interface ShortfallEntry {
     transferId: string;
     remainingAmount: string;
@@ -831,6 +1072,8 @@ declare const STORE_KEYS: {
     readonly deliveryJournal: "delivery-journal";
     readonly mintJournal: "mint-journal";
     readonly nftMintJournal: "nft-mint-journal";
+    readonly customMintJournal: "custom-mint-journal";
+    readonly burnJournal: "burn-journal";
     readonly shortfalls: "shortfalls";
     readonly settlingLinks: "settling";
     readonly streamCursor: (s: StreamName) => string;
@@ -839,167 +1082,6 @@ declare const STORE_KEYS: {
     readonly knownSpends: "known-spends";
 };
 
-/**
- * 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;
-}
-
 interface HistoryWireAsset {
     coinId: string;
     amount: string;
@@ -1368,6 +1450,7 @@ declare class PaymentsFacade implements PaymentsV2 {
     }): Token[];
     coinless(): CoinlessToken[];
     tokenData(tokenId: string): Promise<Uint8Array | null>;
+    tokenJustification(tokenId: string): Promise<Uint8Array | null>;
     nft(tokenId: string): Promise<NftView | null>;
     nfts(tokenIds: readonly string[]): Promise<ReadonlyMap<string, NftView>>;
     private readDeps;
@@ -1391,6 +1474,10 @@ declare class PaymentsFacade implements PaymentsV2 {
     }>;
     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>;
     resumeNow(): Promise<void>;
     /** §5.1 restore — awaited by the session latch BEFORE streams resume; never coalesced onto a pre-restore pass. */
     handleEpochChange(_newEpoch: string): Promise<void>;
@@ -1398,7 +1485,7 @@ declare class PaymentsFacade implements PaymentsV2 {
     private runConvergencePass;
     private convergeBody;
     private nowMs;
-    /** One snapshot serves the coin and the NFT mint, live and replayed. */
+    /** One snapshot serves the coin, NFT and custom mints and the burn, live and replayed. */
     private mintDeps;
     /** The ONE place a send() outcome is shaped: success emits in finishSend, a
      *  CLEAN rejection emits `transfer:updated{status:'failed'}` here (§4). */
@@ -1436,9 +1523,8 @@ declare class PaymentsFacade implements PaymentsV2 {
     /** Nothing delivered → UNWRAPPED; after ≥1 delivered leg every failure surfaces as PartialSendConflictError over the settled set. */
     private softAbort;
     private mintInner;
-    /** A live mint under a fresh id — its replay stays hands-off while this attempt runs. */
-    private ownedMint;
-    private tokenInServerInventory;
+    /** A live money op under a fresh id — its replay stays hands-off while this attempt runs (§7). */
+    private ownedOp;
     private engine;
     private newId;
     private seedHeldStates;
@@ -1449,4 +1535,4 @@ declare class PaymentsFacade implements PaymentsV2 {
 declare const HEARTBEAT_SEED_MS = 5000;
 declare const HEARTBEAT_CAP_MS = 120000;
 
-export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintNftRequest, type MintResult, NFT_DOCUMENT_MEDIA_TYPE, NFT_LINK_TAG, NFT_MAX_PAYLOAD_BYTES, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintJournalEntry, type NftSignatureContext, type NftSignatureStatus, type NftView, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendCoinlessRequest, type SendRequest, type SendWholeTokenRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, encodeNftContent, isNftDocumentLink, isRetryableAckError, parseNftDocument, parseNftPayload, supportsDeterministicMint, sweepSupersededState, verifyNftLinkContent };
+export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type BurnJournalEntry, type BurnRequest, type BurnResult, type CheckpointReseeder, type ConnectionStatus, type CustomMintJournalEntry, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintCustomRequest, type MintJournalEntry, type MintNftRequest, type MintResult, NFT_DOCUMENT_MEDIA_TYPE, NFT_LINK_TAG, NFT_MAX_PAYLOAD_BYTES, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintJournalEntry, type NftSignatureContext, type NftSignatureStatus, type NftView, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingBurn, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendCoinlessRequest, type SendRequest, type SendWholeTokenRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, encodeNftContent, isNftDocumentLink, isRetryableAckError, parseNftDocument, parseNftPayload, supportsDeterministicMint, sweepSupersededState, verifyNftLinkContent };