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

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+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';
 export { BindingInfo, ConnectionEventListener, IdentityBindingParams, NostrClient, NostrClientOptions, NostrKeyManager, areSameNametag, decryptNametag, encryptNametag, hashAddressForTag, hashNametag, isPhoneNumber, normalizeNametag } from '@unicitylabs/nostr-js-sdk';
 
 /**
@@ -155,6 +157,9 @@ declare function isNftDocumentLink(content: NftContent): boolean;
 /** Does `bytes` match the link's sha256? Pure, sync. */
 declare function verifyNftLinkContent(link: NftLink, bytes: Uint8Array): boolean;
 
+/** `none_*` = coinless; `bare_collection` = a dialect this SDK cannot read. */
+type ValueEnvelope = 'sphere' | 'bare_collection' | 'none_tag' | 'none_other' | 'none_absent';
+
 /**
  * token-engine/types.ts — the FROZEN, sphere-domain contract surface.
  *
@@ -170,6 +175,76 @@ declare function verifyNftLinkContent(link: NftLink, bytes: Uint8Array): boolean
  *   Track B codes callers against it (using FakeTokenEngine until A lands).
  */
 
+/**
+ * Coin identifier. Canonical form is the lowercase hex of the v2 AssetId;
+ * human symbols (e.g. "UCT") are resolved to hex via the registry before use.
+ */
+type CoinId = string;
+/** One fungible position inside a token. */
+interface SphereAsset {
+    readonly coinId: CoinId;
+    readonly amount: bigint;
+}
+/** The decoded, app-defined value carried by a token (v2 Token itself is value-less). */
+interface SphereValue {
+    readonly assets: readonly SphereAsset[];
+}
+/**
+ * Storage-and-display token. Format version + network let storage migrate
+ * independently of the SDK's own CBOR. The decoded value is re-derivable from
+ * `token`, so it is NOT stored — only cached at runtime on SphereToken.value.
+ */
+interface TokenBlob {
+    /**
+     * Genesis-stable token id — 64-char lowercase hex of the v2 `TokenId.bytes`
+     * (same across every state of the token). Stored on the blob so dedup / listing
+     * / tombstone keys need no engine call. `createTokenStateKey = ${tokenId}_${hash}`.
+     */
+    readonly tokenId: string;
+    /** CBOR bytes of the v2 Token (`Token.toCBOR()`). */
+    readonly token: Uint8Array;
+}
+/**
+ * A wallet token. `sdkToken` is the OPAQUE engine handle (see file header) —
+ * present for the engine to operate on, never to be touched by callers.
+ */
+interface SphereToken {
+    /** Opaque v2 SDK handle. Do not call methods on this outside token-engine/. */
+    readonly sdkToken: Token$1;
+    /** Serializable form for storage/transport. */
+    readonly blob: TokenBlob;
+    /** Decoded value (cached); null when the token carries no sphere payment data. */
+    readonly value: SphereValue | null;
+    /**
+     * Which value envelope the genesis payload carried (#778). Distinguishes the
+     * reasons `value` is null, which the old boolean predicate collapsed:
+     * `'none_*'` means the token genuinely names no coin — a COINLESS token — while
+     * `'bare_collection'` means it carries coins in the bridged dialect this SDK
+     * does not decode, so a zero here is "cannot read", not "has none". A corrupt
+     * envelope never reaches this field: it throws during classification.
+     */
+    readonly valueEnvelope: ValueEnvelope;
+    /**
+     * Genesis `TokenType`, lowercase hex. The token's CLASS, never its instance —
+     * `blob.tokenId` is the instance key (wallet-api#147). Only as meaningful as its
+     * minter made it: `mint()` and split outputs derive one per operation, so for
+     * value tokens it is per-mint noise. Never a spend gate.
+     */
+    readonly tokenType: string;
+}
+/** 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[];
+}
 /** A token's genesis payload read as an NFT (#785). Display-only. */
 interface NftReading {
     readonly content: NftContent;
@@ -179,6 +254,159 @@ 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.
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * SDK Error Types
+ *
+ * Structured error codes for programmatic error handling in UI.
+ * UI can switch on error.code to show appropriate user-facing messages.
+ *
+ * Errors thrown by provider code (the `./impl/*` bundles) are a different `SphereError` class
+ * copy, so `instanceof SphereError` / `isSphereError()` is false for them: read `code` structurally.
+ *
+ * @example
+ * ```ts
+ * import { PartialSendConflictError, isPossiblyCommittedSendOutcome } from '@unicitylabs/sphere-sdk';
+ *
+ * try {
+ *   await sphere.payments.send({ recipient: '@alice', amount: '1000000', coinId });
+ * } catch (err) {
+ *   if (err instanceof PartialSendConflictError) {
+ *     // Part of the amount already left the wallet and is final. Only err.remainingAmount is still owed:
+ *     // if you pay it, do it as a NEW send of exactly that amount, never the original amount.
+ *     showToast(`Partly sent: ${err.remainingAmount} base units were not sent`);
+ *   } else if (isPossiblyCommittedSendOutcome(err)) {
+ *     // The money may already have left the wallet: never call send() again for this payment.
+ *     showToast('Sent, waiting for confirmation');
+ *   } else {
+ *     switch ((err as { code?: unknown } | null)?.code) {
+ *       case 'SEND_INSUFFICIENT_BALANCE': showToast('Not enough funds'); break;
+ *       case 'INVALID_RECIPIENT': showToast('Recipient not found'); break;
+ *       case 'TRANSPORT_ERROR': showToast('Network connection issue'); break;
+ *       default: showToast(err instanceof Error ? err.message : String(err));
+ *     }
+ *   }
+ * }
+ * ```
+ */
+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';
+declare class SphereError extends Error {
+    readonly code: SphereErrorCode;
+    readonly cause?: unknown;
+    /**
+     * #441 deferred-paid linkage: the transferId of the possibly-committed send,
+     * stamped by `sendOnce` before the error leaves so a payment-request consumer
+     * can durably journal request→transfer and resolve 'paid' only when that
+     * transfer actually completes (never optimistically). Present ONLY on
+     * possibly-committed outcomes ({@link isPossiblyCommittedSendOutcome}).
+     */
+    transferId?: string;
+    constructor(message: string, code: SphereErrorCode, cause?: unknown);
+}
+/**
+ * #677: a send that PARTIALLY completed before losing a source to a concurrent
+ * transfer. At least one earlier leg certified on-chain and was journaled for
+ * delivery (its {@link committedTokenIds}) — that value has irreversibly left
+ * the wallet — but a LATER leg raised `TransferConflictError` (a lost race), and
+ * `send()` could NOT COMPLETE the {@link remainingAmount} from the remaining live
+ * sources. This is the fallback after the internal remainder re-plan gave up —
+ * either insufficient funds OR a transient/transport error during the re-plan
+ * (the underlying reason is on `cause`), not necessarily an "out of funds" state.
+ *
+ * Distinct from `TransferConflictError` on purpose: a bare conflict makes the
+ * caller re-send the FULL amount, paying the already-delivered leg a second
+ * time. Catching THIS type (or `code === 'SEND_PARTIALLY_COMPLETED'`) tells the
+ * caller/UI: the delivered legs are final, the conflicted intent stays OPEN
+ * (resume converges its certified legs), and only the REMAINDER
+ * ({@link remainingAmount}) may be re-planned — under a NEW transferId, never
+ * re-sending the whole amount.
+ *
+ * NOT a subclass of `TransferConflictError` by design: existing conflict
+ * handlers that re-send in full must NOT treat this as an ordinary conflict.
+ */
+declare class PartialSendConflictError extends SphereError {
+    /**
+     * The FIRST partial attempt's transferId — its intent stays open for resume,
+     * and it is the §6 handoff anchor. NOTE: `send()` may re-plan the remainder across
+     * SEVERAL internal attempts before giving up, so {@link committedTokenIds} can
+     * span MULTIPLE transferIds — they do NOT all map to this single id.
+     */
+    readonly transferId: string;
+    /**
+     * Source token ids whose spend already certified on-chain (and whose finished
+     * output blob is journaled for delivery). Their value has already been
+     * delivered; NEVER re-send these. May accumulate across several internal
+     * remainder-re-plan attempts (so not all are journaled under {@link transferId}).
+     */
+    readonly committedTokenIds: readonly string[];
+    /**
+     * The still-undelivered portion (base units, decimal string) — `send()` could
+     * not COMPLETE it from the remaining live sources (insufficient funds or a
+     * transient error; see `cause`). Re-plan ONLY this amount, under a new
+     * transferId; the delivered legs converge via the recipient's §6 claim.
+     */
+    readonly remainingAmount: string;
+    constructor(message: string, transferId: string, committedTokenIds: readonly string[], remainingAmount: string, cause?: unknown);
+}
+/**
+ * #441: true when a send failed with an outcome where the payment has (or may
+ * have) irreversibly left the wallet — a post-commit sync-pending / keep-open
+ * certification state, or a `PartialSendConflictError`. Such a send completes (or
+ * has already partially completed) via resume/claim and MUST NOT be re-sent, so
+ * a persisted "paid" state must stay non-payable. A `false` result is a clean
+ * pre-commit failure — nothing left the wallet, safe to re-pay.
+ */
+declare function isPossiblyCommittedSendOutcome(err: unknown): boolean;
+/**
+ * Type guard to check if an error is a SphereError
+ */
+declare function isSphereError(err: unknown): err is SphereError;
+
 interface SendRequest {
     recipient: string;
     amount: string;
@@ -195,6 +423,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;
@@ -286,6 +548,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. */
@@ -300,6 +564,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[];
     }>;
@@ -309,113 +577,6 @@ interface PaymentsV2 {
     readonly requests: PaymentsRequestsApi;
 }
 
-/**
- * SDK Error Types
- *
- * Structured error codes for programmatic error handling in UI.
- * UI can switch on error.code to show appropriate user-facing messages.
- *
- * Errors thrown by provider code (the `./impl/*` bundles) are a different `SphereError` class
- * copy, so `instanceof SphereError` / `isSphereError()` is false for them: read `code` structurally.
- *
- * @example
- * ```ts
- * import { PartialSendConflictError, isPossiblyCommittedSendOutcome } from '@unicitylabs/sphere-sdk';
- *
- * try {
- *   await sphere.payments.send({ recipient: '@alice', amount: '1000000', coinId });
- * } catch (err) {
- *   if (err instanceof PartialSendConflictError) {
- *     // Part of the amount already left the wallet and is final. Only err.remainingAmount is still owed:
- *     // if you pay it, do it as a NEW send of exactly that amount, never the original amount.
- *     showToast(`Partly sent: ${err.remainingAmount} base units were not sent`);
- *   } else if (isPossiblyCommittedSendOutcome(err)) {
- *     // The money may already have left the wallet: never call send() again for this payment.
- *     showToast('Sent, waiting for confirmation');
- *   } else {
- *     switch ((err as { code?: unknown } | null)?.code) {
- *       case 'SEND_INSUFFICIENT_BALANCE': showToast('Not enough funds'); break;
- *       case 'INVALID_RECIPIENT': showToast('Recipient not found'); break;
- *       case 'TRANSPORT_ERROR': showToast('Network connection issue'); break;
- *       default: showToast(err instanceof Error ? err.message : String(err));
- *     }
- *   }
- * }
- * ```
- */
-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';
-declare class SphereError extends Error {
-    readonly code: SphereErrorCode;
-    readonly cause?: unknown;
-    /**
-     * #441 deferred-paid linkage: the transferId of the possibly-committed send,
-     * stamped by `sendOnce` before the error leaves so a payment-request consumer
-     * can durably journal request→transfer and resolve 'paid' only when that
-     * transfer actually completes (never optimistically). Present ONLY on
-     * possibly-committed outcomes ({@link isPossiblyCommittedSendOutcome}).
-     */
-    transferId?: string;
-    constructor(message: string, code: SphereErrorCode, cause?: unknown);
-}
-/**
- * #677: a send that PARTIALLY completed before losing a source to a concurrent
- * transfer. At least one earlier leg certified on-chain and was journaled for
- * delivery (its {@link committedTokenIds}) — that value has irreversibly left
- * the wallet — but a LATER leg raised `TransferConflictError` (a lost race), and
- * `send()` could NOT COMPLETE the {@link remainingAmount} from the remaining live
- * sources. This is the fallback after the internal remainder re-plan gave up —
- * either insufficient funds OR a transient/transport error during the re-plan
- * (the underlying reason is on `cause`), not necessarily an "out of funds" state.
- *
- * Distinct from `TransferConflictError` on purpose: a bare conflict makes the
- * caller re-send the FULL amount, paying the already-delivered leg a second
- * time. Catching THIS type (or `code === 'SEND_PARTIALLY_COMPLETED'`) tells the
- * caller/UI: the delivered legs are final, the conflicted intent stays OPEN
- * (resume converges its certified legs), and only the REMAINDER
- * ({@link remainingAmount}) may be re-planned — under a NEW transferId, never
- * re-sending the whole amount.
- *
- * NOT a subclass of `TransferConflictError` by design: existing conflict
- * handlers that re-send in full must NOT treat this as an ordinary conflict.
- */
-declare class PartialSendConflictError extends SphereError {
-    /**
-     * The FIRST partial attempt's transferId — its intent stays open for resume,
-     * and it is the §6 handoff anchor. NOTE: `send()` may re-plan the remainder across
-     * SEVERAL internal attempts before giving up, so {@link committedTokenIds} can
-     * span MULTIPLE transferIds — they do NOT all map to this single id.
-     */
-    readonly transferId: string;
-    /**
-     * Source token ids whose spend already certified on-chain (and whose finished
-     * output blob is journaled for delivery). Their value has already been
-     * delivered; NEVER re-send these. May accumulate across several internal
-     * remainder-re-plan attempts (so not all are journaled under {@link transferId}).
-     */
-    readonly committedTokenIds: readonly string[];
-    /**
-     * The still-undelivered portion (base units, decimal string) — `send()` could
-     * not COMPLETE it from the remaining live sources (insufficient funds or a
-     * transient error; see `cause`). Re-plan ONLY this amount, under a new
-     * transferId; the delivered legs converge via the recipient's §6 claim.
-     */
-    readonly remainingAmount: string;
-    constructor(message: string, transferId: string, committedTokenIds: readonly string[], remainingAmount: string, cause?: unknown);
-}
-/**
- * #441: true when a send failed with an outcome where the payment has (or may
- * have) irreversibly left the wallet — a post-commit sync-pending / keep-open
- * certification state, or a `PartialSendConflictError`. Such a send completes (or
- * has already partially completed) via resume/claim and MUST NOT be re-sent, so
- * a persisted "paid" state must stay non-payable. A `false` result is a clean
- * pre-commit failure — nothing left the wallet, safe to re-pay.
- */
-declare function isPossiblyCommittedSendOutcome(err: unknown): boolean;
-/**
- * Type guard to check if an error is a SphereError
- */
-declare function isSphereError(err: unknown): err is SphereError;
-
 interface MasterKey {
     privateKey: string;
     chainCode: string;
@@ -2399,52 +2560,6 @@ interface DiscoverAddressesResult {
     aborted: boolean;
 }
 
-/**
- * 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.
- */
-
-/**
- * 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>;
@@ -3035,6 +3150,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 {
@@ -3078,6 +3195,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 {
@@ -3151,6 +3270,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 {
@@ -3220,6 +3341,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 {
@@ -3307,6 +3430,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;
@@ -5022,4 +5147,4 @@ declare function normalizeAddress(address: string): string;
  */
 declare function addressesMatch(a: string, b: string): boolean;
 
-export { AUTH_CHALLENGE_PREFIX, type AddressInfo, type AddressType, type AggregatorEvent, type AggregatorEventCallback, type AggregatorEventType, type AggregatorProvider, type Asset, type BaseProvider, type BroadcastHandler, type BroadcastMessage, COIN_TYPES, ChallengeTemplateError, type CheckNetworkHealthOptions, CoinGeckoPriceProvider, type CoinlessToken, CommunicationsModule, type CommunicationsModuleConfig, type CommunicationsModuleDependencies, type ComposingIndicator, type ConversationPage, type CreateGroupOptions, DEFAULT_AGGREGATOR_TIMEOUT, DEFAULT_DERIVATION_PATH, DEFAULT_GROUP_RELAYS, DEFAULT_MARKET_API_URL, DEFAULT_NOSTR_RELAYS, type DecryptionProgressCallback, type DerivationMode, type DirectMessage, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type FullIdentity, type GetConversationPageOptions, GroupChatModule, type GroupChatModuleConfig, type GroupChatModuleDependencies, type GroupData, type GroupMemberData, type GroupMessageData, GroupRole, GroupVisibility, type HealthCheckFn, type HistoryRecord, type Identity, type IdentityConfig, type IncomingBroadcast, type IncomingMessage, type IncomingTransfer, type InitProgress, type InitProgressCallback, type InitProgressStep, type IntentStatus, type IntentType, LIMITS, type LegacyFileParseResult, type LegacyFileParsedData, type LegacyFileType, type LogHandler, type LogLevel, type LoggerConfig, type MarketIntent, MarketModule, type MarketModuleConfig, type MarketModuleDependencies, type MessageHandler, type MintNftRequest, NETWORKS, NFT_DOCUMENT_MEDIA_TYPE, NFT_LINK_TAG, NFT_MAX_PAYLOAD_BYTES, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, NIP29_KINDS, NOSTR_EVENT_KINDS, NO_PAYMENTS, type NetworkHealthResult, type NetworkType, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftSignatureContext, type NftSignatureStatus, type NftView, type OracleEvent, type OracleEventCallback, type OracleEventType, type OracleProvider, type ParsedAddress, PartialSendConflictError, type PeerInfo, type PostIntentRequest, type PostIntentResult, type PricePlatform, type PriceProvider, type PriceProviderConfig, type ProviderMetadata, type ProviderRole, type ProviderStatus, type ProviderStatusInfo, type RegistryNetwork, SIGN_MESSAGE_PREFIX, STORAGE_KEYS_ADDRESS, STORAGE_KEYS_GLOBAL, STORAGE_PREFIX, type SearchFilters, type SearchIntentResult, type SearchOptions, type SearchResult, type ServiceHealthResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereEventHandler, type SphereEventMap, type SphereEventType, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type SphereStatus, type StorageProvider, TEST_NOSTR_RELAYS, TIMEOUTS, type Token, type TokenDefinition, type TokenIcon, type TokenPrice, TokenRegistry, type TokenStatus, type TokenTransferDetail, type TrackedAddress, type TrackedAddressEntry, type HistoryRecord as TransactionHistoryEntry, type TransferRequest, type TransferResult, type TransferStatus, type TransportEvent, type TransportEventCallback, type TransportEventType, type TransportProvider, type WalletApiOption, type WalletApiTransportConfig, type WalletInfo, type WalletJSON, type WalletJSONExportOptions, type WalletSource, addressesMatch, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, coinIdsMatch, createCommunicationsModule, createGroupChatModule, createKeyPair, createMarketModule, createPriceProvider, createSphere, decrypt, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptTextFormatKey, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveFieldEncryptionKey, deriveKeyAtPath, doubleSha256, encodeNftContent, encrypt, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateMasterKey, generateMnemonic, getAddressId, getAddressStorageKey, getCoinIdByName, getCoinIdBySymbol, getPublicKey, getTokenDecimals, getTokenDefinition, getTokenIconUrl, getTokenName, getTokenSymbol, hash160, hashSignMessage, hexToBytes, identityFromMnemonicSync, initSphere, isKnownToken, isNftDocumentLink, isPossiblyCommittedSendOutcome, isSphereError, isTextWalletEncrypted, isValidAddress, isValidDirectAddress, isValidNametag, isValidPrivateKey, isWalletTextFormat, loadSphere, logger, mnemonicToSeedSync, normalizeAddress, normalizeCoinId, parseAddress, parseAndDecryptWalletText, parseNftDocument, parseNftPayload, parseTokenAmount, parseWalletText, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifyChallengeTemplate, verifyNftLinkContent, verifySignedMessage };
+export { AUTH_CHALLENGE_PREFIX, type AddressInfo, type AddressType, type AggregatorEvent, type AggregatorEventCallback, type AggregatorEventType, type AggregatorProvider, type Asset, type BaseProvider, type BroadcastHandler, type BroadcastMessage, type BurnParams, COIN_TYPES, ChallengeTemplateError, type CheckNetworkHealthOptions, CoinGeckoPriceProvider, type CoinlessToken, CommunicationsModule, type CommunicationsModuleConfig, type CommunicationsModuleDependencies, type ComposingIndicator, type ConversationPage, type CreateGroupOptions, DEFAULT_AGGREGATOR_TIMEOUT, DEFAULT_DERIVATION_PATH, DEFAULT_GROUP_RELAYS, DEFAULT_MARKET_API_URL, DEFAULT_NOSTR_RELAYS, type DecryptionProgressCallback, type DerivationMode, type DirectMessage, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type FullIdentity, type GetConversationPageOptions, GroupChatModule, type GroupChatModuleConfig, type GroupChatModuleDependencies, type GroupData, type GroupMemberData, type GroupMessageData, GroupRole, GroupVisibility, type HealthCheckFn, type HistoryRecord, type Identity, type IdentityConfig, type IncomingBroadcast, type IncomingMessage, type IncomingTransfer, type InitProgress, type InitProgressCallback, type InitProgressStep, type IntentStatus, type IntentType, LIMITS, type LegacyFileParseResult, type LegacyFileParsedData, type LegacyFileType, type LogHandler, type LogLevel, type LoggerConfig, type MarketIntent, MarketModule, type MarketModuleConfig, type MarketModuleDependencies, type MessageHandler, type MintNftRequest, NETWORKS, NFT_DOCUMENT_MEDIA_TYPE, NFT_LINK_TAG, NFT_MAX_PAYLOAD_BYTES, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, NIP29_KINDS, NOSTR_EVENT_KINDS, NO_PAYMENTS, type NetworkHealthResult, type NetworkType, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftSignatureContext, type NftSignatureStatus, type NftView, type OracleEvent, type OracleEventCallback, type OracleEventType, type OracleProvider, type ParsedAddress, PartialSendConflictError, type PeerInfo, type PostIntentRequest, type PostIntentResult, type PricePlatform, type PriceProvider, type PriceProviderConfig, type ProviderMetadata, type ProviderRole, type ProviderStatus, type ProviderStatusInfo, type RegistryNetwork, SIGN_MESSAGE_PREFIX, STORAGE_KEYS_ADDRESS, STORAGE_KEYS_GLOBAL, STORAGE_PREFIX, type SearchFilters, type SearchIntentResult, type SearchOptions, type SearchResult, type ServiceHealthResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereEventHandler, type SphereEventMap, type SphereEventType, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type SphereStatus, type StorageProvider, TEST_NOSTR_RELAYS, TIMEOUTS, type Token, type TokenDefinition, type TokenIcon, type TokenPlugin, type TokenPrice, TokenRegistry, type TokenStatus, type TokenTransferDetail, type TrackedAddress, type TrackedAddressEntry, type HistoryRecord as TransactionHistoryEntry, type TransferRequest, type TransferResult, type TransferStatus, type TransportEvent, type TransportEventCallback, type TransportEventType, type TransportProvider, type WalletApiOption, type WalletApiTransportConfig, type WalletInfo, type WalletJSON, type WalletJSONExportOptions, type WalletSource, addressesMatch, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, coinIdsMatch, createCommunicationsModule, createGroupChatModule, createKeyPair, createMarketModule, createPriceProvider, createSphere, decrypt, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptTextFormatKey, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveFieldEncryptionKey, deriveKeyAtPath, doubleSha256, encodeNftContent, encrypt, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateMasterKey, generateMnemonic, getAddressId, getAddressStorageKey, getCoinIdByName, getCoinIdBySymbol, getPublicKey, getTokenDecimals, getTokenDefinition, getTokenIconUrl, getTokenName, getTokenSymbol, hash160, hashSignMessage, hexToBytes, identityFromMnemonicSync, initSphere, isKnownToken, isNftDocumentLink, isPossiblyCommittedSendOutcome, isSphereError, isTextWalletEncrypted, isValidAddress, isValidDirectAddress, isValidNametag, isValidPrivateKey, isWalletTextFormat, loadSphere, logger, mnemonicToSeedSync, normalizeAddress, normalizeCoinId, parseAddress, parseAndDecryptWalletText, parseNftDocument, parseNftPayload, parseTokenAmount, parseWalletText, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifyChallengeTemplate, verifyNftLinkContent, verifySignedMessage };