@unicitylabs/sphere-sdk 0.14.0-dev.1 → 0.14.0-dev.2

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

@@ -0,0 +1,1069 @@
+import { Token as Token$1 } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
+
+/**
+ * token-engine/types.ts — the FROZEN, sphere-domain contract surface.
+ *
+ * Design rule (anti-corruption): the public ITokenEngine port speaks ONLY
+ * sphere-domain types — `Uint8Array` pubkeys, `string` coin ids, `bigint`
+ * amounts, plain enums. The v2 state-transition SDK has exactly ONE foothold
+ * here: `SphereToken.sdkToken`, an OPAQUE handle. Callers must treat it as
+ * opaque (store it, hand it back to the engine) and never call methods on it —
+ * they cannot, since the ESLint boundary forbids them importing the SDK.
+ *
+ * Both migration tracks freeze against this file:
+ *   Track A implements it (token-engine internals).
+ *   Track B codes callers against it (using FakeTokenEngine until A lands).
+ */
+
+/** The wallet identity at the engine boundary. The private key never appears in a DTO. */
+interface EngineIdentity {
+    /** 33-byte compressed secp256k1 public key (stable across the migration — Path A). */
+    readonly chainPubkey: Uint8Array;
+}
+/**
+ * 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 {
+    /** Blob format version (sphere storage migrations; independent of SDK CBOR). */
+    readonly v: number;
+    /** NetworkId.id the token belongs to (mainnet=1 / testnet=2 / local=3). */
+    readonly network: number;
+    /**
+     * 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;
+}
+interface MintParams {
+    /** Recipient's 33-byte compressed chain pubkey; engine derives the predicate. */
+    readonly recipientPubkey: Uint8Array;
+    /** Value to embed in the mint; null mints a value-less token. */
+    readonly value?: SphereValue | null;
+}
+/**
+ * Mint a NON-value (data) token: arbitrary opaque `data` (e.g. serialized invoice
+ * terms), a custom `tokenType`, and a deterministic `salt` → a stable,
+ * terms-derived `tokenId`. The minted token has `value === null` (it carries data,
+ * not coins); read the bytes back with `readTokenData`.
+ */
+interface MintDataTokenParams {
+    readonly recipientPubkey: Uint8Array;
+    /** Opaque token payload (the engine does not interpret it). */
+    readonly data: Uint8Array;
+    /** Token type bytes; defaults to a random type when omitted. */
+    readonly tokenType?: Uint8Array;
+    /** Salt bytes; deterministic salt → deterministic (terms-derived) tokenId. */
+    readonly salt?: Uint8Array;
+}
+interface TransferParams {
+    /** The token to spend (must be owned by this engine's identity). */
+    readonly token: SphereToken;
+    /** Recipient's 33-byte compressed chain pubkey. */
+    readonly recipientPubkey: Uint8Array;
+    /** Optional opaque on-chain memo carried on the transfer (read back via `readMemo`). */
+    readonly data?: Uint8Array;
+}
+/**
+ * One split output = one single-coin token. To split a multi-coin token, emit
+ * one output per coin (the recipient receives the value as several tokens; the
+ * SDK enforces per-coin conservation). If a single multi-coin output token is
+ * ever needed, generalize this to `assets: readonly SphereAsset[]` (additive).
+ */
+interface SplitOutput {
+    readonly recipientPubkey: Uint8Array;
+    readonly coinId: CoinId;
+    readonly amount: bigint;
+    /** Optional opaque memo carried in this output's value envelope (read back via `readMemo`). */
+    readonly data?: Uint8Array;
+}
+interface SplitParams {
+    /** The token to split (its total per coin must equal the sum of outputs). */
+    readonly token: SphereToken;
+    /** Desired outputs; value conservation is enforced by the SDK split. */
+    readonly outputs: readonly SplitOutput[];
+}
+interface SplitResult {
+    /**
+     * One minted token per requested output, **index-aligned with
+     * `SplitParams.outputs`** — `outputs[i]` is the token for `params.outputs[i]`
+     * (so a payee/change split can rely on positional order). Guaranteed by both
+     * the real engine and FakeTokenEngine.
+     */
+    readonly outputs: readonly SphereToken[];
+}
+/** Verification outcome, flattened to sphere-domain (no SDK status enum leaks). */
+interface EngineVerifyResult {
+    readonly ok: boolean;
+    /** Human-readable reason when `ok` is false (mapped from the SDK verification status). */
+    readonly reason?: string;
+}
+
+/**
+ * Storage Provider Interface
+ * Platform-independent storage abstraction
+ */
+
+/**
+ * Basic key-value storage provider
+ * All operations are async for platform flexibility
+ */
+interface StorageProvider extends BaseProvider {
+    /**
+     * Set identity for scoped storage
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Get value by key
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set value by key
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Remove key
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Check if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get all keys with optional prefix filter
+     */
+    keys(prefix?: string): Promise<string[]>;
+    /**
+     * Clear all keys with optional prefix filter
+     */
+    clear(prefix?: string): Promise<void>;
+    /**
+     * Save tracked addresses (only user state: index, hidden, timestamps)
+     */
+    saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
+    /**
+     * Load tracked addresses
+     */
+    loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
+}
+
+/**
+ * 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;
+    /**
+     * 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>;
+    /** 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;
+}
+
+/**
+ * SDK2 Core Types
+ * Platform-independent type definitions
+ */
+type ProviderStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+interface ProviderMetadata {
+    readonly id: string;
+    readonly name: string;
+    readonly type: 'local' | 'cloud' | 'p2p' | 'network';
+    readonly description?: string;
+}
+interface BaseProvider extends ProviderMetadata {
+    connect(config?: unknown): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+}
+interface Identity {
+    /** 33-byte compressed secp256k1 public key (for L3 chain) */
+    readonly chainPubkey: string;
+    /** L3 DIRECT address (DIRECT://...) */
+    readonly directAddress?: string;
+    readonly ipnsName?: string;
+    readonly nametag?: string;
+}
+interface FullIdentity extends Identity {
+    readonly privateKey: string;
+}
+type TokenStatus = 'pending' | 'submitted' | 'confirmed' | 'transferring' | 'spent' | 'invalid';
+interface Token {
+    readonly id: string;
+    readonly coinId: string;
+    readonly symbol: string;
+    readonly name: string;
+    readonly decimals: number;
+    readonly iconUrl?: string;
+    readonly amount: string;
+    status: TokenStatus;
+    readonly createdAt: number;
+    updatedAt: number;
+    readonly sdkData?: string;
+    /**
+     * Lazy inventory record (sdk-changes S2): the token's VALUE metadata came
+     * from the storage provider's `listInventory()` view and its blob has not
+     * been downloaded — `sdkData` is absent and the blob is fetched on demand
+     * (`getToken`) only when the token is selected for a spend.
+     */
+    readonly lazy?: boolean;
+    /**
+     * #625 (self-healing coin selection): a send selected this source but its state was already spent
+     * on-chain (`TransferConflictError`). It is KEPT in inventory (visible, recoverable by a resync —
+     * never auto-removed) but EXCLUDED from spend selection, so coin-selection picks live tokens and the
+     * send self-heals instead of wedging on a stale source.
+     */
+    suspectedSpent?: boolean;
+}
+interface Asset {
+    readonly coinId: string;
+    readonly symbol: string;
+    readonly name: string;
+    readonly decimals: number;
+    readonly iconUrl?: string;
+    readonly totalAmount: string;
+    readonly tokenCount: number;
+    /** Sum of confirmed token amounts (smallest units) */
+    readonly confirmedAmount: string;
+    /** Sum of unconfirmed (submitted/pending) token amounts (smallest units) */
+    readonly unconfirmedAmount: string;
+    /** Number of confirmed tokens aggregated */
+    readonly confirmedTokenCount: number;
+    /** Number of unconfirmed tokens aggregated */
+    readonly unconfirmedTokenCount: number;
+    /** Number of tokens currently being sent (in-flight, NOT spendable) */
+    readonly transferringTokenCount: number;
+    /**
+     * Sum of in-flight (`'transferring'`) token amounts (smallest units). These
+     * tokens are LEAVING the wallet during an active send, so they are excluded
+     * from {@link totalAmount}, {@link confirmedAmount}, and
+     * {@link unconfirmedAmount} — surfaced here so a UI can still show a "Sending"
+     * badge without inflating the spendable balance.
+     */
+    readonly transferringAmount: string;
+    /** Price per whole unit in USD (null if PriceProvider not configured) */
+    readonly priceUsd: number | null;
+    /** Price per whole unit in EUR (null if PriceProvider not configured) */
+    readonly priceEur: number | null;
+    /** 24h price change percentage (null if unavailable) */
+    readonly change24h: number | null;
+    /** Total fiat value in USD: (totalAmount / 10^decimals) * priceUsd */
+    readonly fiatValueUsd: number | null;
+    /** Total fiat value in EUR */
+    readonly fiatValueEur: number | null;
+}
+type TransferStatus = 'pending' | 'submitted' | 'confirmed' | 'delivered' | 'completed' | 'failed';
+/**
+ * Per-token transfer detail tracking the on-chain commitment or split operation
+ * for each source token involved in a transfer.
+ */
+interface TokenTransferDetail {
+    /** Source token ID that was consumed in this transfer */
+    readonly sourceTokenId: string;
+    /** Transfer method used for this token */
+    readonly method: 'direct' | 'split';
+    /** Aggregator commitment request ID hex (for direct transfers) */
+    readonly requestIdHex?: string;
+    /** Split group ID (for split transfers — correlates sender/recipient/change tokens) */
+    readonly splitGroupId?: string;
+    /** Nostr event ID (for split transfers delivered via Nostr) */
+    readonly nostrEventId?: string;
+}
+interface TransferResult {
+    readonly id: string;
+    status: TransferStatus;
+    readonly tokens: Token[];
+    /** Per-token transfer details — one entry per source token consumed */
+    readonly tokenTransfers: TokenTransferDetail[];
+    error?: string;
+    /**
+     * True when the send certified on-chain but the recipient-side delivery did not land
+     * (covenant §3.1 — issue #621): the source is terminally spent, the finished blob is
+     * journaled, and the sender is NOT failed. Distinguishes "sent, delivery deferred" from
+     * a real send failure. See {@link deliveryState}.
+     */
+    deliveryPending?: boolean;
+    /** 'landed' = delivered to the recipient's mailbox; 'pending-delivery' = certified, journaled, awaiting (re-)delivery. */
+    deliveryState?: 'landed' | 'pending-delivery';
+}
+interface IncomingTransfer {
+    readonly id: string;
+    readonly senderPubkey: string;
+    readonly senderNametag?: string;
+    readonly tokens: Token[];
+    readonly memo?: string;
+    readonly receivedAt: number;
+}
+/**
+ * Minimal data stored in persistent storage for a tracked address.
+ * Only contains user state — derived fields are computed on load.
+ */
+interface TrackedAddressEntry {
+    /** HD derivation index (0, 1, 2, ...) */
+    readonly index: number;
+    /** Whether this address is hidden from UI display */
+    hidden: boolean;
+    /** Timestamp (ms) when this address was first activated */
+    readonly createdAt: number;
+    /** Timestamp (ms) of last modification */
+    updatedAt: number;
+}
+
+interface SendRequest {
+    recipient: string;
+    amount: string;
+    coinId: string;
+    memo?: string;
+}
+interface MintResult {
+    success: boolean;
+    tokenId?: string;
+    error?: 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;
+}
+interface PaymentsV2 {
+    assets(coinId?: string): Promise<Asset[]>;
+    tokens(filter?: {
+        coinId?: string;
+    }): Token[];
+    history(page?: {
+        before?: string;
+        limit?: number;
+    }): Promise<HistoryPage>;
+    send(req: SendRequest): Promise<TransferResult>;
+    mint(coinId: string, amount: bigint): Promise<MintResult>;
+    receive(): Promise<{
+        transfers: IncomingTransfer[];
+    }>;
+    readonly requests: PaymentsRequestsApi;
+}
+interface PaymentsV2Events {
+    'transfer:incoming': IncomingTransfer;
+    'transfer:updated': TransferResult;
+    'transfer:attention': {
+        transferId: string;
+        code: string;
+        detail?: string;
+    };
+    'inventory:updated': Record<string, never>;
+    'history:updated': Record<string, never>;
+    'payment_request:incoming': PaymentRequestView;
+    'payment_request:updated': {
+        id: string;
+        status: PaymentRequestStatus;
+    };
+    'connection:status': {
+        status: 'connected' | 'degraded' | 'offline';
+    };
+}
+
+interface InventoryAsset {
+    coinId: string;
+    amount: string;
+}
+interface InventoryItem {
+    tokenId: string;
+    status: 'active' | 'removed';
+    seq: number;
+    stateHash: string;
+    assets?: InventoryAsset[];
+}
+interface InventoryPage {
+    cursor: number;
+    syncEpoch: string;
+    more: boolean;
+    items: InventoryItem[];
+}
+interface ApplyDeltaResult {
+    cursor: number;
+    syncEpoch: string;
+}
+interface StoragePort {
+    listInventory(since?: number): Promise<InventoryPage>;
+    balances(): Promise<{
+        coinId: string;
+        total: string;
+        tokenCount: number;
+    }[]>;
+    getBlobs(tokenIds: string[]): Promise<Map<string, Uint8Array>>;
+    uploadBlobs(blobs: {
+        sha256: string;
+        bytes: Uint8Array;
+    }[]): Promise<Map<string, string>>;
+    applyDelta(delta: {
+        transferId: string;
+        spent: string[];
+        added: {
+            tokenId: string;
+            key: string;
+        }[];
+    }): Promise<ApplyDeltaResult>;
+}
+interface DeliveryReceipt {
+    deliveryId: string;
+}
+interface IncomingDelivery {
+    deliveryId: string;
+    transferId?: string;
+    senderPubkey?: string;
+    senderNametag?: string;
+    memo?: string;
+    fetchBlob(): Promise<Uint8Array>;
+    cursor: string;
+}
+interface DeliverOptions {
+    transferId: string;
+    memo?: string;
+    senderNametag?: string;
+}
+interface DeliveryPort {
+    bindDeliveryKeys(derive: (blob: Uint8Array) => Promise<{
+        tokenId: string;
+        stateHash: string;
+    }>): void;
+    deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
+    deliverBatch?(recipientPubkey: string, blobs: Uint8Array[], options: DeliverOptions): Promise<DeliveryReceipt[]>;
+    incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
+    onWake?(cb: () => void): () => void;
+}
+
+interface IntentPayload {
+    v: 2;
+    recipient: string;
+    coinId: string;
+    amount: string;
+    memo?: string;
+    direct: string[];
+    split?: {
+        tokenId: string;
+        splitAmount: string;
+        remainderAmount: string;
+    };
+    spentStates?: Record<string, {
+        local: string;
+        protocol: string;
+    }>;
+}
+type MachinePhase = 'PLANNED' | 'INTENT_OPEN' | 'CERTIFYING' | 'DELIVERING' | 'APPLYING' | 'CLOSING' | 'DONE' | 'FAILED';
+interface PlannedOp {
+    kind: 'direct' | 'split';
+    opIndex: number;
+    sourceTokenId: string;
+    deliveredAmount: bigint;
+}
+interface OpOutcome {
+    op: PlannedOp;
+    certified: boolean;
+    recipientBlob?: Uint8Array;
+    changeBlob?: Uint8Array;
+    error?: unknown;
+}
+type OutcomeClass = 'keep-open' | 'conflict' | 'clean-reject' | 'other';
+
+interface ScopedKV {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+declare function createScopedKV(storage: StorageProvider, network: string, chainPubkey: string): ScopedKV;
+interface IntentBackstopEntry {
+    transferId: string;
+    payloadEnvelope: string;
+    requiresSeedClose: boolean;
+    disposition: 'open' | 'abortPending' | 'aborted';
+    createdAt: number;
+}
+interface CheckpointCacheEntry {
+    transferId: string;
+    opIndex: number;
+    envelope: string;
+}
+interface DeliveryJournalEntry {
+    transferId: string;
+    opIndex: number;
+    recipientPubkey: string;
+    blobHex: string;
+    memo?: string;
+    attempts: number;
+    deferredUntil?: number;
+    undeliverable?: boolean;
+}
+interface MintJournalEntry {
+    mintId: string;
+    coinId: string;
+    amount: string;
+    tokenId: string;
+    createdAt: number;
+}
+interface ShortfallEntry {
+    transferId: string;
+    remainingAmount: string;
+    coinId: string;
+    recipient: string;
+    committedTokenIds: string[];
+    createdAt: number;
+}
+interface SettlingLink {
+    requestId: string;
+    transferId: string;
+    committed: boolean;
+    createdAt: number;
+}
+type StreamName = 'inventory' | 'mailbox' | 'payment_requests' | 'history';
+interface StreamCursor {
+    cursor: number | string;
+    syncEpoch: string;
+}
+declare const STORE_KEYS: {
+    readonly intentBackstop: "intents";
+    readonly checkpointCache: "checkpoints";
+    readonly deliveryJournal: "delivery-journal";
+    readonly mintJournal: "mint-journal";
+    readonly shortfalls: "shortfalls";
+    readonly settlingLinks: "settling";
+    readonly streamCursor: (s: StreamName) => string;
+    readonly epochLatch: "epoch-latch";
+};
+
+type RequestWireStatus = 'open' | 'paid' | 'declined' | 'expired';
+interface RequestWire {
+    readonly id: string;
+    readonly seq: number;
+    readonly fromPubkey: string;
+    readonly toPubkey: string;
+    readonly assets: readonly {
+        readonly coinId: string;
+        readonly amount: string;
+    }[];
+    readonly memo?: string;
+    readonly status: RequestWireStatus;
+    readonly transferId: string | null;
+    readonly createdAt: string;
+    readonly expiresAt?: string;
+}
+interface RequestsPageWire {
+    readonly requests: readonly RequestWire[];
+    readonly more: boolean;
+    readonly cursor: number | string | null;
+    readonly syncEpoch: number;
+}
+interface RequestsWireClient {
+    createPaymentRequest(input: {
+        toPubkey: string;
+        assets: {
+            coinId: string;
+            amount: string;
+        }[];
+        memo?: string;
+        expiresAt?: string;
+    }): Promise<RequestWire>;
+    listPaymentRequests(params: {
+        role: 'incoming';
+        since?: number;
+    }): Promise<RequestsPageWire>;
+    respondPaymentRequest(id: string, response: {
+        action: 'paid';
+        transferId: string;
+    } | {
+        action: 'declined';
+    }): Promise<RequestWire>;
+}
+interface RequestMemoCodec {
+    encrypt(peerPubkey: string, bundle: {
+        memo?: string;
+        senderNametag?: string;
+    }): string | undefined;
+    decrypt(peerPubkey: string, envelope: string): {
+        memo?: string;
+        senderNametag?: string;
+    };
+}
+type RequestsEmit = <K extends 'payment_request:incoming' | 'payment_request:updated'>(event: K, payload: PaymentsV2Events[K]) => void;
+interface RequestsDeps {
+    readonly client: RequestsWireClient;
+    readonly kv: ScopedKV;
+    readonly ownPubkey: string;
+    readonly send: (request: SendRequest) => Promise<TransferResult>;
+    readonly resolvePubkey: (identifier: string) => Promise<string | null>;
+    readonly listAbortedTransferIds: () => Promise<string[]>;
+    readonly emit: RequestsEmit;
+    readonly memo: RequestMemoCodec;
+    readonly ownNametag?: () => string | undefined;
+    readonly now?: () => number;
+}
+interface ResumeOutcomes {
+    readonly resumed: readonly string[];
+    readonly conflicted: readonly string[];
+    readonly open: readonly string[];
+}
+declare class Requests implements PaymentsRequestsApi {
+    private readonly deps;
+    private readonly mirror;
+    private hydrated;
+    private drainInFlight;
+    private journal;
+    private journalLoad;
+    private journalTail;
+    private readonly payInFlight;
+    private reconcileInFlight;
+    constructor(deps: RequestsDeps);
+    private now;
+    private ensureJournalLoaded;
+    private mutateJournal;
+    private writeLink;
+    private clearLink;
+    drainIncoming(): Promise<void>;
+    private doDrain;
+    private surface;
+    private decryptMemo;
+    private setStatus;
+    list(): PaymentRequestView[];
+    create(to: string, terms: {
+        coinId: string;
+        amount: string;
+        memo?: string;
+    }): Promise<{
+        success: boolean;
+        requestId?: string;
+        error?: string;
+    }>;
+    pay(id: string): Promise<TransferResult>;
+    private payInner;
+    /** 'paid' respond leg: 409 = already resolved = idempotent success; other errors defer. */
+    private respondPaid;
+    decline(id: string): Promise<void>;
+    dismissProcessed(): void;
+    reconcile(outcomes: ResumeOutcomes): Promise<void>;
+    private reconcileUnaccounted;
+    private resolvePaid;
+    private revertPayable;
+}
+
+interface HistoryWireAsset {
+    coinId: string;
+    amount: string;
+}
+interface HistoryWireRecord {
+    dedupKey: string;
+    id: string;
+    type: 'SENT' | 'RECEIVED' | 'MINT';
+    assets: HistoryWireAsset[];
+    ts: string;
+    transferId?: string;
+    tokenId?: string;
+    counterpartyPubkey?: string;
+    counterpartyNametag?: string;
+    memo?: string;
+}
+interface HistoryClient {
+    listHistory(options?: {
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        records: readonly HistoryWireRecord[];
+        more: boolean;
+        cursor: string | null;
+    }>;
+    postHistory(records: HistoryWireRecord[]): Promise<unknown>;
+}
+
+interface RegistryReader {
+    getSymbol(coinId: string): string;
+    getName(coinId: string): string;
+    getDecimals(coinId: string): number;
+    getIconUrl(coinId: string): string | null;
+}
+interface PriceQuote {
+    readonly priceUsd: number;
+    readonly priceEur?: number;
+    readonly change24h?: number;
+}
+interface PriceReader {
+    getPrices(tokenNames: string[]): Promise<Map<string, PriceQuote>>;
+}
+
+/**
+ * TODO(mint-F13 seam): `engine.mint` today salts fresh per call, so an
+ * interrupted mint is not re-derivable. When F13 lands transferId-seeded
+ * determinism the engine advertises it here and replay re-derives by mintId.
+ */
+interface DeterministicMintCapable {
+    readonly deterministicMint: true;
+    deriveMintTokenId(params: MintParams, mintId: string): Promise<string>;
+}
+declare function supportsDeterministicMint(engine: ITokenEngine): engine is ITokenEngine & DeterministicMintCapable;
+interface RecipientInfo {
+    chainPubkey: string;
+    network: string;
+    nametag?: string;
+}
+interface FacadeSession {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    subscribeStream(stream: 'inventory' | 'mailbox' | 'payment_requests', handler: () => void): () => void;
+}
+interface IntentWireLike {
+    transferId: string;
+    payload: string;
+    createdAt: string;
+}
+/** Structural slice of WalletApiV2Client the facade consumes directly. */
+interface FacadeClient extends HistoryClient, RequestsWireClient {
+    putIntent(transferId: string, payloadEnvelope: string, requiresSeedClose?: boolean): Promise<void>;
+    listIntents(status?: 'open' | 'aborted'): Promise<IntentWireLike[]>;
+    abortIntent(transferId: string): Promise<void>;
+    completeIntent(transferId: string, signature?: string): Promise<void>;
+}
+interface PaymentsFacadeDeps {
+    session: FacadeSession;
+    client: FacadeClient;
+    storagePort: StoragePort;
+    deliveryPort: DeliveryPort;
+    checkpointStore: SplitCheckpointStore;
+    /** Initial engine source; setEngine() swaps what FUTURE operations snapshot. */
+    engineRef: () => ITokenEngine;
+    kv: ScopedKV;
+    registry: RegistryReader;
+    price?: PriceReader;
+    emit: (event: string, payload: unknown) => void;
+    resolveRecipient: (identifier: string) => Promise<RecipientInfo | null>;
+    signComplete: (transferId: string) => Promise<string>;
+    /** S6 self-scoped field key: intent payload envelope + history memo/nametag. */
+    fieldKey: Uint8Array;
+    /** The session's network — a recipient not verifiably on it is refused (§5.6). */
+    network: string;
+    ownPubkey: string;
+    ownNametag?: () => string | undefined;
+    requestMemo: RequestMemoCodec;
+    syncEpoch?: () => string;
+    now?: () => number;
+    newId?: () => string;
+    workBudget?: number;
+    receivePollMs?: number;
+}
+
+/** Max re-plans after a conflicted attempt (#625/#677 parity with the old send loop). */
+declare const MAX_RESELECT = 8;
+declare const ATTENTION_MINT_UNRESOLVED = "mint:unresolved";
+declare class PaymentsFacade implements PaymentsV2 {
+    private readonly deps;
+    private readonly view;
+    private readonly ledger;
+    private readonly queue;
+    private readonly machine;
+    private readonly machineDeps;
+    private readonly machineStores;
+    private readonly historyStore;
+    private readonly receiveLoop;
+    private readonly heldStates;
+    private readonly ownPubkeyBytes;
+    readonly requests: Requests;
+    private currentEngine;
+    private readonly pendingOps;
+    private unsubscribers;
+    private started;
+    constructor(deps: PaymentsFacadeDeps);
+    start(): Promise<void>;
+    /** §7 same-address restart gate: resolves only after in-flight ops settle. */
+    stop(): Promise<void>;
+    /** Swaps what FUTURE operations snapshot; in-flight ops finish on the old engine. */
+    setEngine(next: ITokenEngine): void;
+    assets(coinId?: string): Promise<Asset[]>;
+    tokens(filter?: {
+        coinId?: string;
+    }): Token[];
+    history(page?: {
+        before?: string;
+        limit?: number;
+    }): Promise<HistoryPage>;
+    send(request: SendRequest): Promise<TransferResult>;
+    receive(): Promise<{
+        transfers: IncomingTransfer[];
+    }>;
+    mint(coinId: string, amount: bigint): Promise<MintResult>;
+    private sendWithPolicy;
+    /** §5.6 cross-network deposit trap: refused BEFORE any reserve/certification. */
+    private requireSameNetworkRecipient;
+    private runAttempt;
+    /**
+     * Partial outcome (#677/#690): the shortfall is already durable (written by
+     * the machine BEFORE complete). Accumulate the settled set, then re-plan ONLY
+     * the remainder under a NEW transferId — never the full amount.
+     */
+    private consumePartial;
+    /**
+     * One attempt's failure disposition: possibly-committed → rethrow UNWRAPPED;
+     * backstop still 'open' (committed>0) → converge via the same machine's
+     * resumeIntent; clean conflict with a demoted source → bounded full re-plan.
+     */
+    private disposeFailedAttempt;
+    /** #677/#690: ≥1 leg committed — the SAME machine, resumed in-process, converges it. */
+    private convergePartial;
+    private disposeConvergeFailure;
+    private planAndMaterialize;
+    /** Reserve happened synchronously inside queue.plan; mark + declare with no await between. */
+    private markPlanned;
+    private materialize;
+    /** isSpent sweep over the attempt's sources; demote proven-spent states (durable). */
+    private demoteSpentSources;
+    private settleSuccess;
+    private settleFailure;
+    /** Open intent: sources stay reserved + in-flight (§5.2) until resume adopts them. */
+    private settleKeepOpen;
+    private settlePartial;
+    /** Release spent sources only AFTER the mirror refresh tombstoned them. */
+    private refreshThenRelease;
+    private accumulate;
+    private finishSend;
+    /**
+     * With nothing delivered the error passes UNWRAPPED (identity + cause kept);
+     * after ≥1 delivered leg EVERY failure surfaces as PartialSendConflictError
+     * over the accumulated settled set — never bare, never a full-amount retry.
+     */
+    private partialize;
+    /** #441: possibly-committed errors must carry the transferId for the settling journal. */
+    private stampTransferId;
+    private softAbort;
+    private mintInner;
+    private finalizeMint;
+    private replayMints;
+    private replayMint;
+    private mintParams;
+    private tokenInServerInventory;
+    private engine;
+    private newId;
+    private runResume;
+    private seedHeldStates;
+    private toUiToken;
+    private track;
+    private trackTail;
+}
+
+export { ATTENTION_MINT_UNRESOLVED, type ApplyDeltaResult, type CheckpointCacheEntry, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MachinePhase, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PlannedOp, type RecipientInfo, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, supportsDeterministicMint };