@unicitylabs/sphere-sdk 0.9.1-dev.6 → 0.9.1-dev.7

package/dist/impl/shared/wallet-api/index.d.ts

@@ -0,0 +1,1770 @@
+/**
+ * Oracle Provider Interface
+ * Platform-independent Unicity oracle abstraction
+ *
+ * Post v1-cutover the oracle is a thin NETWORK-CONFIG provider: it loads the
+ * root trust base (JSON) and exposes the gateway URL + API key. The v2 token
+ * engine (token-engine/) builds its own aggregator clients from these — no
+ * SDK client objects cross this boundary anymore.
+ *
+ * `validateToken` survives as a best-effort JSON-RPC check for LEGACY v1 TXF
+ * tokens still present in storage (display-path only); v2 blob tokens are
+ * verified via the engine (`engine.verify` + `engine.isSpent`).
+ */
+
+interface OracleProvider extends BaseProvider {
+    /**
+     * Initialize the provider. Loads the trust base JSON via the configured
+     * platform loader when none is passed explicitly.
+     *
+     * @param trustBaseJson - Optional raw trust-base JSON (overrides the loader).
+     */
+    initialize(trustBaseJson?: unknown): Promise<void>;
+    /**
+     * Validate a LEGACY v1 TXF token against the aggregator (best-effort RPC).
+     * v2 blob tokens never reach this — they are verified via the token engine.
+     */
+    validateToken(tokenData: unknown): Promise<ValidationResult>;
+    /** Raw trust-base JSON (the engine parses it; the networkId comes from it). */
+    getTrustBaseJson(): unknown | null;
+    /** Gateway (aggregator) base URL. */
+    getAggregatorUrl(): string;
+    /** Gateway API key, when the gateway requires one (e.g. testnet2). */
+    getApiKey(): string | undefined;
+}
+interface ValidationResult {
+    valid: boolean;
+    spent: boolean;
+    error?: string;
+    stateHash?: string;
+}
+
+/**
+ * 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).
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * Transport Provider Interface
+ * Platform-independent P2P messaging abstraction
+ */
+
+/**
+ * P2P messaging transport provider
+ */
+interface TransportProvider extends BaseProvider {
+    /**
+     * Set identity for signing/encryption.
+     * If the transport is already connected, reconnects with the new identity.
+     */
+    setIdentity(identity: FullIdentity): void | Promise<void>;
+    /**
+     * Send encrypted direct message
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
+     */
+    sendMessage(recipientTransportPubkey: string, content: string): Promise<string>;
+    /**
+     * Subscribe to incoming direct messages
+     * @returns Unsubscribe function
+     */
+    onMessage(handler: MessageHandler): () => void;
+    /**
+     * Send token transfer payload
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
+     */
+    sendTokenTransfer(recipientTransportPubkey: string, payload: TokenTransferPayload): Promise<string>;
+    /**
+     * Subscribe to incoming token transfers
+     * @returns Unsubscribe function
+     */
+    onTokenTransfer(handler: TokenTransferHandler): () => void;
+    /**
+     * Resolve any identifier to full peer information.
+     * Accepts @nametag, bare nametag, DIRECT://, PROXY://, L1 address, chain pubkey, or transport pubkey.
+     * @param identifier - Any supported identifier format
+     * @returns PeerInfo or null if not found
+     */
+    resolve?(identifier: string): Promise<PeerInfo | null>;
+    /**
+     * Resolve nametag to public key
+     */
+    resolveNametag?(nametag: string): Promise<string | null>;
+    /**
+     * Resolve nametag to full peer information
+     * Returns transportPubkey, chainPubkey, l1Address, directAddress
+     */
+    resolveNametagInfo?(nametag: string): Promise<PeerInfo | null>;
+    /**
+     * Resolve a DIRECT://, PROXY://, or L1 address to full peer info.
+     * Performs reverse lookup: address → binding event → PeerInfo.
+     * @param address - L3 address (DIRECT://... or PROXY://...) or L1 address (alpha1...)
+     * @returns PeerInfo or null if no binding found for this address
+     */
+    resolveAddressInfo?(address: string): Promise<PeerInfo | null>;
+    /**
+     * Resolve transport pubkey to full peer info.
+     * Queries binding events authored by the given transport pubkey.
+     * @param transportPubkey - Transport-specific pubkey (e.g. 64-char hex string)
+     * @returns PeerInfo or null if no binding found
+     */
+    resolveTransportPubkeyInfo?(transportPubkey: string): Promise<PeerInfo | null>;
+    /**
+     * Batch-resolve multiple transport pubkeys to peer info.
+     * Used for HD address discovery: derives transport pubkeys for indices 0..N
+     * and queries binding events in a single batch.
+     * @param transportPubkeys - Array of transport-specific pubkeys to look up
+     * @returns Array of PeerInfo for pubkeys that have binding events (may be shorter than input)
+     */
+    discoverAddresses?(transportPubkeys: string[]): Promise<PeerInfo[]>;
+    /**
+     * Recover nametag for current identity by decrypting stored encrypted nametag
+     * Used after wallet import to recover associated nametag
+     * @returns Decrypted nametag or null if none found
+     */
+    recoverNametag?(): Promise<string | null>;
+    /**
+     * Publish identity binding event.
+     * Without nametag: publishes base binding (chainPubkey, l1Address, directAddress).
+     * With nametag: adds nametag hash, proxy address, encrypted nametag for recovery.
+     * Uses parameterized replaceable event (kind 30078, d=hash(nostrPubkey)).
+     * @returns true if successful, false if nametag is taken by another pubkey
+     */
+    publishIdentityBinding?(chainPubkey: string, l1Address: string, directAddress: string, nametag?: string): Promise<boolean>;
+    /**
+     * Subscribe to broadcast messages (global/channel)
+     */
+    subscribeToBroadcast?(tags: string[], handler: BroadcastHandler): () => void;
+    /**
+     * Publish broadcast message
+     */
+    publishBroadcast?(content: string, tags?: string[]): Promise<string>;
+    /**
+     * Send payment request to a recipient
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
+     */
+    sendPaymentRequest?(recipientTransportPubkey: string, request: PaymentRequestPayload): Promise<string>;
+    /**
+     * Subscribe to incoming payment requests
+     * @returns Unsubscribe function
+     */
+    onPaymentRequest?(handler: PaymentRequestHandler): () => void;
+    /**
+     * Send response to a payment request
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
+     */
+    sendPaymentRequestResponse?(recipientTransportPubkey: string, response: PaymentRequestResponsePayload): Promise<string>;
+    /**
+     * Subscribe to incoming payment request responses
+     * @returns Unsubscribe function
+     */
+    onPaymentRequestResponse?(handler: PaymentRequestResponseHandler): () => void;
+    /**
+     * Send a read receipt for a message
+     * @param recipientTransportPubkey - Transport pubkey of the message sender
+     * @param messageEventId - Event ID of the message being acknowledged
+     */
+    sendReadReceipt?(recipientTransportPubkey: string, messageEventId: string): Promise<void>;
+    /**
+     * Subscribe to incoming read receipts
+     * @returns Unsubscribe function
+     */
+    onReadReceipt?(handler: ReadReceiptHandler): () => void;
+    /**
+     * Send typing indicator to a recipient
+     * @param recipientTransportPubkey - Transport pubkey of the conversation partner
+     */
+    sendTypingIndicator?(recipientTransportPubkey: string): Promise<void>;
+    /**
+     * Subscribe to incoming typing indicators
+     * @returns Unsubscribe function
+     */
+    onTypingIndicator?(handler: TypingIndicatorHandler): () => void;
+    /**
+     * Send composing indicator to a recipient using NIP-44 encrypted gift wrap
+     * @param recipientTransportPubkey - Transport pubkey of the conversation partner
+     * @param content - JSON payload with senderNametag and expiresIn
+     */
+    sendComposingIndicator?(recipientTransportPubkey: string, content: string): Promise<void>;
+    /**
+     * Subscribe to incoming composing indicators
+     * @returns Unsubscribe function
+     */
+    onComposing?(handler: ComposingHandler): () => void;
+    /**
+     * Get list of configured relay URLs
+     */
+    getRelays?(): string[];
+    /**
+     * Get list of currently connected relay URLs
+     */
+    getConnectedRelays?(): string[];
+    /**
+     * Add a relay dynamically
+     * @returns true if added successfully
+     */
+    addRelay?(relayUrl: string): Promise<boolean>;
+    /**
+     * Remove a relay dynamically
+     * @returns true if removed successfully
+     */
+    removeRelay?(relayUrl: string): Promise<boolean>;
+    /**
+     * Check if a relay is configured
+     */
+    hasRelay?(relayUrl: string): boolean;
+    /**
+     * Check if a relay is currently connected
+     */
+    isRelayConnected?(relayUrl: string): boolean;
+    /**
+     * Set fallback 'since' timestamp for event subscriptions.
+     * Used when switching to an address that has never subscribed before.
+     * The transport uses this instead of 'now' as the initial since filter,
+     * ensuring events sent while the address was inactive are not missed.
+     * Consumed once by the next subscription setup, then cleared.
+     *
+     * @param sinceSeconds - Unix timestamp in seconds
+     */
+    setFallbackSince?(sinceSeconds: number): void;
+    /**
+     * Set fallback 'since' timestamp for DM (gift-wrap) subscriptions.
+     * Used when no persisted DM timestamp exists in storage (e.g. first connect).
+     * Consumed once by the next subscription setup, then cleared.
+     *
+     * @param sinceSeconds - Unix timestamp in seconds
+     */
+    setFallbackDmSince?(sinceSeconds: number): void;
+    /**
+     * Fetch pending events from transport (one-shot query).
+     * Creates a temporary subscription, processes events through normal handlers,
+     * and resolves after EOSE (End Of Stored Events).
+     */
+    fetchPendingEvents?(): Promise<void>;
+    /**
+     * Register a handler to be called when the chat subscription receives EOSE
+     * (End Of Stored Events), indicating that historical DMs have been delivered.
+     * The handler fires at most once per subscription lifecycle.
+     *
+     * @returns Unsubscribe function
+     */
+    onChatReady?(handler: () => void): () => void;
+}
+interface IncomingMessage {
+    id: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if known from NIP-17 unwrap) */
+    senderNametag?: string;
+    content: string;
+    timestamp: number;
+    encrypted: boolean;
+    /** Set when this is a self-wrap replay (sent message recovered from relay) */
+    isSelfWrap?: boolean;
+    /** Recipient pubkey — only present on self-wrap replays */
+    recipientTransportPubkey?: string;
+}
+type MessageHandler = (message: IncomingMessage) => void;
+interface TokenTransferPayload {
+    /** Serialized token data */
+    token: string;
+    /** Inclusion proof */
+    proof: unknown;
+    /** Optional memo */
+    memo?: string;
+    /** Sender info */
+    sender?: {
+        /** Transport-specific pubkey */
+        transportPubkey: string;
+        nametag?: string;
+    };
+}
+interface IncomingTokenTransfer {
+    id: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    payload: TokenTransferPayload;
+    timestamp: number;
+}
+type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void | Promise<void>;
+interface PaymentRequestPayload {
+    /** Amount requested (in smallest units) */
+    amount: string | bigint;
+    /** Coin/token type ID */
+    coinId: string;
+    /** Message/memo for recipient */
+    message?: string;
+    /** Recipient's nametag (who should pay) */
+    recipientNametag?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+interface IncomingPaymentRequest {
+    /** Event ID */
+    id: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if included in encrypted content) */
+    senderNametag?: string;
+    /** Parsed request data */
+    request: {
+        requestId: string;
+        amount: string;
+        coinId: string;
+        message?: string;
+        recipientNametag?: string;
+        metadata?: Record<string, unknown>;
+    };
+    /** Timestamp */
+    timestamp: number;
+}
+type PaymentRequestHandler = (request: IncomingPaymentRequest) => void;
+type PaymentRequestResponseType = 'accepted' | 'rejected' | 'paid';
+interface PaymentRequestResponsePayload {
+    /** Original request ID */
+    requestId: string;
+    /** Response type */
+    responseType: PaymentRequestResponseType;
+    /** Optional message */
+    message?: string;
+    /** Transfer ID (if paid) */
+    transferId?: string;
+}
+interface IncomingPaymentRequestResponse {
+    /** Event ID */
+    id: string;
+    /** Transport-specific pubkey of responder */
+    responderTransportPubkey: string;
+    /** Parsed response data */
+    response: {
+        requestId: string;
+        responseType: PaymentRequestResponseType;
+        message?: string;
+        transferId?: string;
+    };
+    /** Timestamp */
+    timestamp: number;
+}
+type PaymentRequestResponseHandler = (response: IncomingPaymentRequestResponse) => void;
+interface IncomingBroadcast {
+    id: string;
+    /** Transport-specific pubkey of author */
+    authorTransportPubkey: string;
+    content: string;
+    tags: string[];
+    timestamp: number;
+}
+type BroadcastHandler = (broadcast: IncomingBroadcast) => void;
+/**
+ * Resolved peer identity information.
+ * Returned by resolve methods — contains all public address formats for a peer.
+ * The nametag field is optional (only present if a nametag is registered).
+ */
+interface PeerInfo {
+    /** Nametag name (without @), if registered */
+    nametag?: string;
+    /** Transport-specific pubkey (for messaging/encryption) */
+    transportPubkey: string;
+    /** 33-byte compressed secp256k1 public key (for L3 chain) */
+    chainPubkey: string;
+    /** L1 address (alpha1...) */
+    l1Address: string;
+    /** L3 DIRECT address (DIRECT://...) */
+    directAddress: string;
+    /** Event timestamp */
+    timestamp: number;
+}
+interface IncomingReadReceipt {
+    /** Transport-specific pubkey of the sender who read the message */
+    senderTransportPubkey: string;
+    /** Event ID of the message that was read */
+    messageEventId: string;
+    /** Timestamp */
+    timestamp: number;
+}
+type ReadReceiptHandler = (receipt: IncomingReadReceipt) => void;
+interface IncomingTypingIndicator {
+    /** Transport-specific pubkey of the sender who is typing */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if known) */
+    senderNametag?: string;
+    /** Timestamp */
+    timestamp: number;
+}
+type TypingIndicatorHandler = (indicator: IncomingTypingIndicator) => void;
+type ComposingHandler = (indicator: ComposingIndicator) => void;
+
+/**
+ * transport/delivery-provider.ts — the `DeliveryProvider` port (sdk-changes S7,
+ * covenant §3.1-6).
+ *
+ * The seam that keeps the delivery rail swappable. In Unicity, a transfer —
+ * after certification — is just a file handoff, so the port is deliberately
+ * tiny: hand a finished token blob to a recipient, pull incoming deliveries,
+ * acknowledge them. `WalletApiMailboxProvider`
+ * (impl/shared/wallet-api/WalletApiMailboxProvider.ts) is the reference
+ * implementation; anything that can move a file can implement it (the port
+ * shape must not preclude the old Nostr transport or a future federated
+ * transport — neither is a deliverable here).
+ *
+ * Normative shapes (sdk-changes S7):
+ * - `DeliveryReceipt = { deliveryId }`
+ * - `IncomingDelivery = { deliveryId, transferId?, senderPubkey?, memo?,
+ *   fetchBlob(), cursor }`
+ * - `deliveryId` is the **content-derived** entry id —
+ *   `hex(SHA-256(tokenId bytes ‖ stateHash bytes))` — NEVER a server-assigned
+ *   row id or seq (covenant §3.1-4; the contract suite asserts it). It is
+ *   computed client-side ({@link computeDeliveryId}) and must equal the
+ *   backend's `entry_id` (ARCHITECTURE §6).
+ * - **Custody is a composition-time property, not a per-call flag**:
+ *   implementations take `custody: 'inventory' | 'external'` at construction
+ *   and every ack sends the corresponding `intoInventory` — delivery-only
+ *   safety must never depend on remembering an option at a call site.
+ * - Implementations MUST keep a **persistent `(tokenId, stateHash)` seen-set**
+ *   for incoming deliveries: the recipient-side replay guard is part of the
+ *   port contract, not a server promise (the recipient never trusts the
+ *   backend — ARCHITECTURE §8.2). `deliveryId` is the canonical hash encoding
+ *   of exactly that pair, so a persistent deliveryId set satisfies this.
+ */
+/** Receipt for a delivered blob. `deliveryId` is content-derived — see module doc. */
+interface DeliveryReceipt {
+    deliveryId: string;
+}
+/** Options for {@link DeliveryProvider.deliver}. */
+interface DeliverOptions {
+    /**
+     * The send's transferId (the E.3 intent id / realization seed). Recorded
+     * with the delivery so the recipient can group multi-token payments and the
+     * backend can evidence-check the sender's removals (ARCHITECTURE §5.3/§6).
+     */
+    transferId: string;
+    /** Optional human memo. Implementations encrypt it client-side (S6). */
+    memo?: string;
+}
+/** One incoming delivery pulled from the feed. */
+interface IncomingDelivery {
+    /** Content-derived id — `hex(SHA-256(tokenId bytes ‖ stateHash bytes))`. */
+    deliveryId: string;
+    /** The sender's transferId, when the transport carries it. */
+    transferId?: string;
+    /** The sender's pubkey, when the transport carries it. */
+    senderPubkey?: string;
+    /** Decrypted memo (S6), when present and decryptable. */
+    memo?: string;
+    /** Fetch the finished token blob bytes (the encoded TokenBlob). */
+    fetchBlob(): Promise<Uint8Array>;
+    /** Transport-local resume cursor (opaque to callers). */
+    cursor: string;
+}
+type DeliveryDisposition = 'claimed' | 'rejected';
+/**
+ * Custody mode (composition-time): `'inventory'` — acknowledged deliveries
+ * enter the wallet-api inventory (the full wallet-api preset); `'external'` —
+ * the app's own storage keeps custody and acks perform ZERO inventory writes
+ * (the delivery-only preset, ARCHITECTURE §6 "delivery-only claim").
+ */
+type DeliveryCustody = 'inventory' | 'external';
+interface DeliveryProvider {
+    /** Composition-time custody property — never a per-call flag (S7). */
+    readonly custody: DeliveryCustody;
+    /**
+     * Bind the wallet identity (optional — implementations that authenticate or
+     * encrypt per-wallet need it; mirrors `TokenStorageProvider.setIdentity`).
+     */
+    setIdentity?(identity: {
+        privateKey: string;
+        chainPubkey: string;
+    }): void;
+    /**
+     * Hand a finished token blob to a recipient. `recipientPubkey` is the
+     * recipient's CHAIN pubkey (33-byte compressed secp256k1, hex) — the
+     * canonical Unicity identity (ARCHITECTURE §4); transports that address
+     * recipients differently resolve it themselves.
+     *
+     * MUST be idempotent per (token, state): re-delivering the same finished
+     * blob — including after the recipient claimed — succeeds and returns the
+     * same content-derived `deliveryId` (ARCHITECTURE §6 deposit idempotency).
+     */
+    deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
+    /**
+     * Pull-based feed of incoming deliveries since the given transport-local
+     * cursor (or the provider's persisted cursor when omitted). Yields only
+     * deliveries not yet in the persistent seen-set; completes when the feed is
+     * drained — callers re-invoke on poll/wake. Feeds the existing
+     * transport-agnostic `handleV2Transfer` (sdk-changes S3).
+     */
+    incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    /**
+     * Acknowledge a delivery: `'claimed'` accepts it (with the provider's
+     * composition-time custody), `'rejected'` marks it locally-unverifiable —
+     * terminal for discovery only (the entry stays claimable server-side and
+     * its blob is retained — ARCHITECTURE §6). Both record the delivery in the
+     * persistent seen-set.
+     */
+    ack(deliveryId: string, disposition: DeliveryDisposition): Promise<void>;
+    /**
+     * Optional wake hook: `callback` fires when new deliveries may be available
+     * (e.g. a WS nudge — never a correctness dependency, ARCHITECTURE §9).
+     * Returns an unsubscribe function.
+     */
+    onWake?(callback: () => void): () => void;
+    /**
+     * Late-bind the backend-true (tokenId, stateHash) derivation —
+     * `ITokenEngine.deliveryKeys`. Compositions are engine-less (the engine is
+     * built later); the module that owns both (PaymentsModule) binds this at
+     * init. Implementations that derive ids (S7) MUST use it and fail loudly if
+     * unbound; transports that don't derive may omit the method.
+     */
+    bindDeliveryKeys?(derive: (blobBytes: Uint8Array) => Promise<{
+        tokenId: string;
+        stateHash: string;
+    }>): 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;
+    /** L1 address (alpha1...) */
+    readonly l1Address: string;
+    /** L3 DIRECT address (DIRECT://...) */
+    readonly directAddress?: string;
+    readonly ipnsName?: string;
+    readonly nametag?: string;
+}
+interface FullIdentity extends Identity {
+    readonly privateKey: string;
+}
+interface ComposingIndicator {
+    readonly senderPubkey: string;
+    readonly senderNametag?: string;
+    readonly expiresIn: 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;
+}
+
+/**
+ * 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[]>;
+}
+interface HistoryRecord {
+    /** Composite dedup key (primary key) — e.g. "RECEIVED_v5split_abc123" */
+    dedupKey: string;
+    /** UUID for public API consumption */
+    id: string;
+    type: 'SENT' | 'RECEIVED' | 'SPLIT' | 'MINT';
+    amount: string;
+    coinId: string;
+    symbol: string;
+    timestamp: number;
+    transferId?: string;
+    /** Genesis tokenId this entry relates to (used for dedup) */
+    tokenId?: string;
+    senderPubkey?: string;
+    senderAddress?: string;
+    senderNametag?: string;
+    recipientPubkey?: string;
+    recipientAddress?: string;
+    recipientNametag?: string;
+    /** Optional memo/message attached to the transfer */
+    memo?: string;
+    /** All token IDs in a combined transfer (V6 bundle breakdown) */
+    tokenIds?: Array<{
+        id: string;
+        amount: string;
+        source: 'split' | 'direct';
+    }>;
+}
+/** One fungible position of an inventory item. Amounts are `bigint` in types
+ * (decimal strings on the wallet-api wire — they exceed 2^53). */
+interface InventoryAsset {
+    coinId: string;
+    amount: bigint;
+}
+/**
+ * One row of the inventory view — value metadata only, **no blobs**.
+ * `status: 'removed'` is a tombstone: the token left this inventory (spent, or
+ * handed off at claim) — the only way a stale device learns about removals
+ * (ARCHITECTURE §5.1).
+ */
+interface InventoryItem {
+    /** Genesis-stable 64-hex token id. */
+    tokenId: string;
+    status: 'active' | 'removed';
+    /** Decoded value; absent when unknown (e.g. a tombstone). */
+    assets?: InventoryAsset[];
+    /** Owner change-cursor value at this row's last change (`?since=` deltas). */
+    seq: bigint;
+}
+/** Result of {@link TokenStorageProvider.listInventory}. */
+interface InventoryView {
+    /** Cursor to resume deltas from (`listInventory(cursor)`). */
+    cursor: bigint;
+    /**
+     * Server sync epoch (ARCHITECTURE §5.4/§9): changes ONLY when a server
+     * restore invalidated cursor continuity. On a change, clients discard all
+     * persisted cursors, do a full pull, and re-PUT locally-known open intents.
+     * Local providers (no server) report a constant `0n`.
+     */
+    syncEpoch: bigint;
+    /** Truncated page (PAGE_LIMIT) — loop with `since = cursor` until false. */
+    more: boolean;
+    items: InventoryItem[];
+}
+/** An `added` entry of {@link TokenStorageProvider.applyDelta}: the token id
+ * plus the content-addressed blob-store key of its already-uploaded bytes. */
+interface ApplyDeltaAdded {
+    tokenId: string;
+    /** Content-addressed blob key — `<network>/t/<hex(sha256(blob))>` (ARCHITECTURE §5.2). */
+    key: string;
+}
+interface ApplyDeltaOptions {
+    /**
+     * The wallet-api-storage + other-transport composition (ARCHITECTURE §5.3):
+     * removals cannot be evidence-checked against a mailbox deposit, so the
+     * server records them as `external` (never-collected blob retention).
+     */
+    externalDelivery?: boolean;
+}
+/** Result of an explicit `recoverRemoved()` maintenance run (sdk-changes S2). */
+interface RecoverRemovedResult {
+    /** Tombstoned tokens re-verified and re-added (reactivation — ARCHITECTURE §5.3). */
+    recovered: string[];
+    /** Tokens the server 409'd as evidenced spends — "actually spent", tombstone kept. */
+    spent: string[];
+    /** Tombstones skipped (matched to a known local spend, or failed local verification). */
+    skipped: string[];
+}
+/**
+ * Storage result types
+ */
+interface SaveResult {
+    success: boolean;
+    cid?: string;
+    error?: string;
+    timestamp: number;
+}
+interface LoadResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    source: 'local' | 'remote' | 'cache';
+    timestamp: number;
+}
+interface SyncResult<T = unknown> {
+    success: boolean;
+    merged?: T;
+    added: number;
+    removed: number;
+    conflicts: number;
+    error?: string;
+}
+/**
+ * Token-specific storage provider
+ * Handles token persistence with sync capabilities
+ */
+interface TokenStorageProvider<TData = unknown> extends BaseProvider {
+    /**
+     * Set identity for storage scope
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Initialize provider (called once after identity is set)
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Shutdown provider
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Save token data
+     */
+    save(data: TData): Promise<SaveResult>;
+    /**
+     * Load token data
+     */
+    load(identifier?: string): Promise<LoadResult<TData>>;
+    /**
+     * Sync local data with remote
+     */
+    sync(localData: TData): Promise<SyncResult<TData>>;
+    /**
+     * The inventory view — value metadata only, never blobs.
+     *
+     * Without `since`: the current active rows. With `since`: every row changed
+     * after that cursor **including tombstones** (`status:'removed'`) — callers
+     * MUST apply tombstones (drop local entries) and loop while `more` is true.
+     * On a `syncEpoch` change the provider discards persisted cursors and
+     * resyncs from scratch (ARCHITECTURE §5.4).
+     *
+     * Whole-blob providers (no change journal) compute the view from the loaded
+     * set: all rows `'active'`, synthetic `seq`/`cursor`, `more: false`.
+     */
+    listInventory(since?: bigint): Promise<InventoryView>;
+    /**
+     * Fetch + decode one token blob on demand (a signed GET for remote
+     * providers; the loaded set for whole-blob providers). Throws when the
+     * token is unknown or carries no v2 blob.
+     */
+    getToken(tokenId: string): Promise<TokenBlob>;
+    /**
+     * Record a spend result: tombstone `spent` tokens, add `added` outputs.
+     * Idempotent by `transferId`. For wallet-api delivery this MUST be called
+     * **after** the mailbox deposit of the same `transferId` — the backend
+     * evidence-checks removals against it (ARCHITECTURE §5.3).
+     */
+    applyDelta(transferId: string, spent: string[], added: ApplyDeltaAdded[], opts?: ApplyDeltaOptions): Promise<void>;
+    /**
+     * Optional maintenance call (sdk-changes S2): re-fetch tombstoned tokens the
+     * client cannot match to a known spend, verify them locally, and re-add
+     * (reactivation). A server 409 means "actually spent" — keep the tombstone.
+     * Only meaningful for providers with server-side tombstones.
+     */
+    recoverRemoved?(): Promise<RecoverRemovedResult>;
+    /**
+     * Check if data exists
+     */
+    exists?(identifier?: string): Promise<boolean>;
+    /**
+     * Clear all data
+     */
+    clear?(): Promise<boolean>;
+    /**
+     * Create a new independent instance of this provider for a different address.
+     * Used by per-address module architecture — each address gets its own
+     * TokenStorageProvider instance to avoid cross-address data contamination.
+     * If not implemented, the provider cannot be used in multi-address mode.
+     */
+    createForAddress?(): TokenStorageProvider<TData>;
+    /**
+     * Subscribe to storage events
+     */
+    onEvent?(callback: StorageEventCallback): () => void;
+    /** Store a history entry (upsert by dedupKey) */
+    addHistoryEntry?(entry: HistoryRecord): Promise<void>;
+    /** Get all history entries sorted by timestamp descending */
+    getHistoryEntries?(): Promise<HistoryRecord[]>;
+    /** Check if a history entry exists by dedupKey */
+    hasHistoryEntry?(dedupKey: string): Promise<boolean>;
+    /** Clear all history entries */
+    clearHistory?(): Promise<void>;
+    /** Bulk import history entries (skip existing dedupKeys). Returns count of newly imported. */
+    importHistoryEntries?(entries: HistoryRecord[]): Promise<number>;
+}
+type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'storage:remote-updated' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
+interface StorageEvent {
+    type: StorageEventType;
+    timestamp: number;
+    data?: unknown;
+    error?: string;
+}
+type StorageEventCallback = (event: StorageEvent) => void;
+interface TxfStorageDataBase {
+    _meta: TxfMeta;
+    _tombstones?: TxfTombstone[];
+    _outbox?: TxfOutboxEntry[];
+    _sent?: TxfSentEntry[];
+    _invalid?: TxfInvalidEntry[];
+    _history?: HistoryRecord[];
+    [key: `_${string}`]: unknown;
+}
+interface TxfMeta {
+    version: number;
+    address: string;
+    ipnsName?: string;
+    formatVersion: string;
+    updatedAt: number;
+}
+interface TxfTombstone {
+    tokenId: string;
+    stateHash: string;
+    timestamp: number;
+}
+interface TxfOutboxEntry {
+    id: string;
+    status: string;
+    tokenId: string;
+    recipient: string;
+    createdAt: number;
+    data: unknown;
+}
+interface TxfSentEntry {
+    tokenId: string;
+    recipient: string;
+    txHash: string;
+    sentAt: number;
+}
+interface TxfInvalidEntry {
+    tokenId: string;
+    reason: string;
+    detectedAt: number;
+}
+
+/**
+ * wallet-api/types.ts — sphere-domain types for the wallet-api client (S1).
+ *
+ * Wire rule (ARCHITECTURE §11/§16): asset amounts are arbitrary-precision
+ * integers carried as decimal strings (`/^[0-9]+$/`) in every JSON body and
+ * response — they exceed 2^53, so they are NEVER a JS `number`. In these types
+ * they are `bigint`; the codec (./codec.ts) converts at the boundary. Cursors
+ * and seqs are `bigint` for the same reason.
+ */
+
+/**
+ * The narrow slice of `StorageProvider` the client needs: the refresh token
+ * (credential hygiene — most-protected storage the platform offers, never a
+ * URL, never logs) and the normative LOCAL copy of open intents (E.3).
+ */
+interface KeyValueStore {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/** Minimal fetch signature (injectable; defaults to `globalThis.fetch`). */
+type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+}) => Promise<FetchResponseLike>;
+interface FetchResponseLike {
+    status: number;
+    ok: boolean;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** Minimal WebSocket surface (browser WebSocket and the `ws` package both satisfy it). */
+interface WebSocketLike {
+    onopen: ((ev?: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((ev?: unknown) => void) | null;
+    onclose: ((ev?: unknown) => void) | null;
+    close(): void;
+}
+type WebSocketFactoryLike = (url: string) => WebSocketLike;
+interface WalletApiClientConfig {
+    /**
+     * Backend base URL. Non-loopback URLs MUST be `https:` (ARCHITECTURE §4
+     * transport rule, enforced client-side at construction) — bearer JWTs,
+     * refresh tokens and signed URLs never transit plaintext off-loopback.
+     */
+    baseUrl: string;
+    /** Network name, e.g. 'testnet2' — required end-to-end (ARCHITECTURE §14). */
+    network: string;
+    /** Client-chosen device label (never a key on its own — ARCHITECTURE §4). */
+    deviceId: string;
+    /** Refresh-token + local-intent persistence (see {@link KeyValueStore}). */
+    storage: KeyValueStore;
+    /** Injectable fetch (defaults to `globalThis.fetch`). */
+    fetchFn?: FetchLike;
+    /** Injectable WebSocket factory (defaults to `globalThis.WebSocket`). */
+    webSocketFactory?: WebSocketFactoryLike;
+    /** Injectable clock (ms since epoch) for challenge plausibility checks. */
+    now?: () => number;
+}
+/** The wallet identity the client authenticates as. */
+interface WalletApiIdentity {
+    /** secp256k1 private key, hex — signs auth challenges; never leaves the client. */
+    privateKey: string;
+    /** 33-byte compressed secp256k1 public key, hex. */
+    chainPubkey: string;
+}
+/** `GET /v1/inventory` page (§16). */
+interface InventoryPage {
+    cursor: bigint;
+    syncEpoch: bigint;
+    more: boolean;
+    items: InventoryItem[];
+}
+/** `GET /v1/balances` entry (§16) — active rows only. */
+interface CoinBalance {
+    coinId: string;
+    total: bigint;
+    tokenCount: number;
+}
+/** `POST /v1/tokens/blob-urls` entry (§16): short-lived signed GET. */
+interface BlobUrlEntry {
+    tokenId: string;
+    getUrl: string;
+}
+/** `POST /v1/tokens/upload-urls` request entry (§5.2): client-side sha256 + size. */
+interface UploadUrlRequest {
+    /** Lowercase hex SHA-256 of the exact blob bytes. */
+    sha256: string;
+    size: number;
+}
+/** `POST /v1/tokens/upload-urls` response entry (§16). */
+interface UploadUrlEntry {
+    sha256: string;
+    /** The derived content-addressed key `<network>/t/<sha256>` (§5.2). */
+    key: string;
+    putUrl: string;
+}
+/** `POST /v1/inventory/apply` request (§5.3/§16). */
+interface ApplyDeltaRequest {
+    transferId: string;
+    spent: string[];
+    added: {
+        tokenId: string;
+        key: string;
+    }[];
+    externalDelivery?: boolean;
+}
+/** Intent row (§16). `payload` is the S6 `enc1.` envelope string, verbatim. */
+interface IntentRecord {
+    transferId: string;
+    payload: string;
+    status: 'open' | 'completed' | 'aborted';
+    createdAt: number;
+}
+/** `POST /v1/mailbox` request (§16). `memo` is the S6 `enc1.` envelope, verbatim. */
+interface MailboxDepositRequest {
+    /** Recipient's 33-byte compressed chain pubkey (hex) — §6 addressing. */
+    recipientPubkey: string;
+    /** Content-addressed blob-store key of the already-uploaded blob (§5.2). */
+    key: string;
+    /** The send's transferId — §5.3 evidence lookup uses the STORED value. */
+    transferId: string;
+    /** Claimed final state hash — `hex(SHA-256(inner token bytes))`. */
+    stateHash: string;
+    /** Claimed genesis-stable token id. */
+    tokenId: string;
+    /** Optional S6-encrypted memo envelope. */
+    memo?: string;
+}
+type MailboxEntryStatus = 'unclaimed' | 'claimed' | 'rejected';
+/** One `GET /v1/mailbox` entry (§16). */
+interface MailboxEntry {
+    /** Content-derived entry id — `hex(SHA-256(tokenId ‖ stateHash))` (§6). */
+    entryId: string;
+    /** Per-recipient gap-free, commit-ordered seq (§9). */
+    seq: bigint;
+    status: MailboxEntryStatus;
+    transferId: string;
+    tokenId: string;
+    /** Decoded value of the deposited blob (per §8.2 step 6). */
+    assets: {
+        coinId: string;
+        amount: bigint;
+    }[];
+    senderPubkey: string;
+    /** S6 `enc1.` envelope, verbatim (the server never sees plaintext). */
+    memo?: string;
+    createdAt: number;
+    /** Signed GET for the blob — present while the blob is retained (§6). */
+    getUrl?: string;
+    /** True once the blob was garbage-collected after resolution (§6). */
+    blobCollected?: boolean;
+}
+/** `GET /v1/mailbox?since=` page (§16). */
+interface MailboxPage {
+    /** Highest contiguous resolved seq — the discovery cursor (§6). */
+    readPointer: bigint;
+    syncEpoch: bigint;
+    more: boolean;
+    entries: MailboxEntry[];
+}
+/** `POST /v1/mailbox/claim` result (§16). */
+interface MailboxClaimResult {
+    claimed: string[];
+    /** Already-claimed entries with their STORED disposition (§6). */
+    alreadyClaimed: {
+        entryId: string;
+        intoInventory: boolean;
+    }[];
+    /** Defensive bucket — an entry that would now violate lineage (§5.3). */
+    failed: {
+        entryId: string;
+        code: string;
+    }[];
+}
+/**
+ * One client-asserted history record (§10 — the server never writes history).
+ * `memo` and `counterpartyNametag` are S6 `enc1.` envelopes, verbatim (§8.3).
+ */
+interface HistoryWireRecord {
+    /** Client dedup key — POST is idempotent by it. */
+    dedupKey: string;
+    /** Client-generated record id (UUID — §16). */
+    id: string;
+    /** §16 enum: 'SENT' | 'RECEIVED' | 'MINT'. */
+    type: string;
+    /** ISO-8601 timestamp with offset (§16 `ts`). */
+    ts: string;
+    /** Decimal-string amounts (§11). */
+    assets: {
+        coinId: string;
+        amount: string;
+    }[];
+    transferId?: string;
+    /** Genesis-stable token id, lowercase hex (§16 — never a `v2_…` UI id). */
+    tokenId?: string;
+    /** 33-byte compressed secp256k1 pubkey, lowercase hex (§16). */
+    counterpartyPubkey?: string;
+    /** S6 envelope. */
+    memo?: string;
+    /** S6 envelope. */
+    counterpartyNametag?: string;
+}
+/** `GET /v1/history` page (§16): newest-first, opaque keyset cursor. */
+interface HistoryPage {
+    records: HistoryWireRecord[];
+    more: boolean;
+    /** Pass as `before` for the next (older) page; null on the last page (§16). */
+    cursor: string | null;
+    syncEpoch: bigint;
+}
+type PaymentRequestWireStatus = 'open' | 'paid' | 'declined' | 'expired';
+/**
+ * One §16 payment request. `memo` is the S6 `enc1.` envelope, verbatim — it
+ * decrypts only under the REQUESTER's wallet key (S6 keys are wallet-scoped),
+ * so the payer surfaces it as absent, never as ciphertext.
+ */
+interface PaymentRequestRecord {
+    id: string;
+    /** Per-payer gap-free, commit-ordered seq (§9/§10) — the incoming cursor unit. */
+    seq: bigint;
+    fromPubkey: string;
+    toPubkey: string;
+    assets: {
+        coinId: string;
+        amount: bigint;
+    }[];
+    /** S6 `enc1.` envelope, verbatim (the server never sees plaintext — §8.3). */
+    memo?: string;
+    status: PaymentRequestWireStatus;
+    /** The fulfilling send's transferId once paid; null otherwise (§16). */
+    transferId: string | null;
+    createdAt: number;
+    /** Server-owned expiry (§10) — the sweep flips overdue requests, never the client. */
+    expiresAt?: number;
+}
+/** `POST /v1/payment-requests` request (§16). */
+interface CreatePaymentRequestInput {
+    /** The payer's 33-byte compressed chain pubkey (lowercase hex) — §10 addressing. */
+    toPubkey: string;
+    assets: {
+        coinId: string;
+        amount: bigint;
+    }[];
+    /** S6 `enc1.` envelope — encrypt client-side BEFORE calling (§8.3). */
+    memo?: string;
+    /** ms since epoch — sent as ISO-8601 (§16). */
+    expiresAt?: number;
+}
+/**
+ * `GET /v1/payment-requests` query (§16). The two role views carry DIFFERENT
+ * cursor families that never mix (the server 422s a mismatch): incoming is
+ * the payer's gap-free `?since=<seq>` stream; outgoing is the requester's
+ * newest-first `?before=<opaque keyset>` backfill.
+ */
+type ListPaymentRequestsParams = {
+    role: 'incoming';
+    status?: PaymentRequestWireStatus;
+    since?: bigint;
+} | {
+    role: 'outgoing';
+    status?: PaymentRequestWireStatus;
+    before?: string;
+};
+/** `GET /v1/payment-requests` page (§16), discriminated by the requested role. */
+type PaymentRequestsPage = {
+    role: 'incoming';
+    requests: PaymentRequestRecord[];
+    more: boolean;
+    /** The §16 `?since=` seq cursor (gap-free — §9). */
+    cursor: bigint;
+    syncEpoch: bigint;
+} | {
+    role: 'outgoing';
+    requests: PaymentRequestRecord[];
+    more: boolean;
+    /** Opaque keyset for the next (older) page; null when drained (§16). */
+    cursor: string | null;
+    syncEpoch: bigint;
+};
+/**
+ * `POST /v1/payment-requests/{id}/respond` body (§16): `paid` REQUIRES the
+ * fulfilling send's transferId, `declined` forbids it — the pairing is in the
+ * type, mirroring the server's validation.
+ */
+type RespondPaymentRequestInput = {
+    action: 'paid';
+    transferId: string;
+} | {
+    action: 'declined';
+};
+/** WS wake nudge (§9): pull that stream's cursor; never a correctness dependency. */
+interface WakeEvent {
+    stream: 'inventory' | 'mailbox' | 'payment_requests';
+    syncEpoch: bigint;
+}
+type WakeCallback = (wake: WakeEvent) => void;
+/** Handle returned by the wake-socket connect. */
+interface WakeSocketHandle {
+    close(): void;
+}
+
+/**
+ * wallet-api/client.ts — `WalletApiClient` (sdk-changes S1).
+ *
+ * A small typed client for the wallet-api backend: challenge→sign→JWT with a
+ * rotating refresh token, typed REST for the §16 endpoints, and the WS wake
+ * channel (ticket flow — §9). Injected into providers (DI; no singletons).
+ *
+ * Cross-cutting rules (S1):
+ * - **Challenge template verification** — the spend key never signs text that
+ *   fails `verifyChallengeTemplate` (prefix + own pubkey + plausible
+ *   timestamps). See ./challenge.ts.
+ * - **Credential hygiene** — the refresh token lives only in the injected
+ *   {@link KeyValueStore} (never a URL, never logged). A rotation-reuse
+ *   revocation or refresh expiry falls back to a fresh challenge→sign cycle —
+ *   silent, since the wallet key is available at unlock. Non-loopback base
+ *   URLs MUST be `https:` (ARCHITECTURE §4 transport rule), enforced at
+ *   construction.
+ * - **Amounts are decimal strings end-to-end**, parsed with `BigInt` (§11) —
+ *   see ./codec.ts.
+ *
+ * The client also keeps the NORMATIVE LOCAL COPY of open intents (E.3): the
+ * server is the primary, but intents are the one server table not
+ * re-derivable from blobs — after a server restore (`syncEpoch` change,
+ * ARCHITECTURE §5.4) the client re-PUTs its locally-known open intents
+ * (idempotent) before anything resumes. `putIntent` persists locally before
+ * the server PUT; the local copy survives a failed PUT as the restore
+ * backstop.
+ */
+
+declare class WalletApiClient {
+    /** Network name (also the blob-key prefix `<network>/t/<sha256>` — §5.2). */
+    readonly network: string;
+    private readonly baseUrl;
+    private readonly deviceId;
+    private readonly storage;
+    private readonly fetchFn;
+    private readonly wsFactory;
+    private readonly now;
+    private identity;
+    private jwt;
+    /** Serializes concurrent re-auth attempts. */
+    private authInFlight;
+    constructor(config: WalletApiClientConfig);
+    /** Bind the wallet identity this client authenticates as. Resets the session. */
+    setIdentity(identity: WalletApiIdentity): void;
+    private requireIdentity;
+    private scopedKey;
+    private refreshTokenKey;
+    /**
+     * Establish a session: try the stored refresh token first (rotating), fall
+     * back to a fresh challenge→sign→verify cycle. Safe to call repeatedly.
+     */
+    signIn(): Promise<void>;
+    private signInInner;
+    /**
+     * `POST /v1/auth/refresh` with the stored token; rotates on success. Any
+     * 4xx (expired, revoked, rotation-reuse revocation) clears the stored token
+     * and reports `false` — the caller falls back to a challenge cycle.
+     */
+    private tryRefresh;
+    /** The challenge→verify cycle (§4 steps 1–3) with template verification (S1). */
+    private challengeSignIn;
+    /** Revoke the session server-side and drop all local credentials. */
+    logout(): Promise<void>;
+    private rawFetch;
+    private readJson;
+    private toError;
+    /**
+     * Authenticated JSON request. A 401 triggers one silent re-auth
+     * (refresh → challenge fallback) and one retry.
+     */
+    private requestJson;
+    /** `GET /v1/inventory?since=` — one page; the caller loops while `more`. */
+    listInventory(since?: bigint): Promise<InventoryPage>;
+    /** `GET /v1/balances` — active rows only. */
+    getBalances(): Promise<CoinBalance[]>;
+    /** `POST /v1/tokens/blob-urls` — owner's active *or tombstoned* rows (§5.3 recovery). */
+    getBlobUrls(tokenIds: string[]): Promise<BlobUrlEntry[]>;
+    /** `POST /v1/tokens/upload-urls` — checksum/length-bound presigned PUTs (§5.2). */
+    getUploadUrls(blobs: UploadUrlRequest[]): Promise<UploadUrlEntry[]>;
+    /**
+     * `POST /v1/inventory/apply` (§5.3). Also marks the local intent copy
+     * completed — the server completes the intent in the same transaction (§16).
+     */
+    applyInventoryDelta(req: ApplyDeltaRequest): Promise<bigint>;
+    /** Download blob bytes from a signed GET URL (the URL itself is the credential). */
+    fetchBlob(getUrl: string): Promise<Uint8Array>;
+    /**
+     * Upload blob bytes to a signed PUT URL. A `412 Precondition Failed` means
+     * the identical blob already exists (content addressing, `If-None-Match: *`
+     * — §5.2) and is treated as success.
+     *
+     * The §5.2 presign binds `x-amz-checksum-sha256` and `if-none-match` (plus
+     * `content-length`) as SIGNED HEADERS — a real S3 endpoint rejects the
+     * SigV4 signature unless the uploader sends them verbatim. (Caught by the
+     * phase-2 harness on first contact with real MinIO — the in-process fake
+     * had only validated the body, not the signed headers.)
+     */
+    uploadBlob(putUrl: string, bytes: Uint8Array): Promise<void>;
+    /**
+     * `POST /v1/mailbox` — deposit an already-uploaded finished blob to the
+     * recipient's mailbox. Idempotent by content-derived `entry_id` (§6): an
+     * existing entry in any status returns `200` with its id, provided the
+     * request's recipient and key match the stored entry (a mismatch is `409`).
+     */
+    depositMailbox(req: MailboxDepositRequest): Promise<string>;
+    /**
+     * `GET /v1/mailbox?since=<seq>` — entries of EVERY status are listable for
+     * any client-chosen `since`; a claimed entry carries a working `getUrl`
+     * while its blob is within retention, `blobCollected: true` afterwards (§6).
+     */
+    listMailbox(since?: bigint): Promise<MailboxPage>;
+    /**
+     * `POST /v1/mailbox/claim` — addressee-only, idempotent ownership handoff
+     * (§6). `intoInventory:false` is the delivery-only claim: the entry resolves
+     * and the pointer advances with ZERO inventory writes.
+     */
+    claimMailbox(entryIds: string[], intoInventory: boolean): Promise<MailboxClaimResult>;
+    /**
+     * `POST /v1/mailbox/reject` — addressee-only; terminal for DISCOVERY only:
+     * the entry counts toward read-pointer contiguity but remains claimable and
+     * its blob is retained (§6 — reject is never a destruction path).
+     */
+    rejectMailbox(entryIds: string[]): Promise<string[]>;
+    /**
+     * `POST /v1/history` — client-asserted records, deduped by `dedupKey` (the
+     * server never writes history rows — §10). `memo`/`counterpartyNametag`
+     * MUST already be S6 envelopes.
+     */
+    postHistoryRecords(records: HistoryWireRecord[]): Promise<void>;
+    /** `GET /v1/history?before=&limit=` — newest-first keyset pages (§10). */
+    listHistory(options?: {
+        before?: string;
+        limit?: number;
+    }): Promise<HistoryPage>;
+    /**
+     * `POST /v1/payment-requests` — create a request addressed to a payer (the
+     * payer's account is auto-provisioned even if they never authenticated —
+     * §4/§9; the per-payer open cap → 429, §5.5). `memo` MUST already be an S6
+     * `enc1.` envelope (§8.3) — only the requester's wallet key decrypts it.
+     */
+    createPaymentRequest(input: CreatePaymentRequestInput): Promise<PaymentRequestRecord>;
+    /**
+     * `GET /v1/payment-requests?role=…` (§16): `'incoming'` is the payer's
+     * gap-free `?since=<seq>` stream (cursor = bigint, the standard §16 since
+     * contract); `'outgoing'` is the requester's newest-first
+     * `?before=<opaque keyset>` backfill (cursor = string | null). The two
+     * cursor families never mix — the server 422s a mismatched parameter, and
+     * the parameter types make it unrepresentable here.
+     */
+    listPaymentRequests<R extends 'incoming' | 'outgoing'>(params: Extract<ListPaymentRequestsParams, {
+        role: R;
+    }>): Promise<Extract<PaymentRequestsPage, {
+        role: R;
+    }>>;
+    /**
+     * `POST /v1/payment-requests/{id}/respond` — addressee-only (§10, non-
+     * addressee → 403); only an `open` request may be responded to (else 409).
+     * `paid` REQUIRES and links the fulfilling send's transferId, `declined`
+     * carries none — the pairing is enforced by {@link RespondPaymentRequestInput}.
+     */
+    respondPaymentRequest(id: string, response: RespondPaymentRequestInput): Promise<PaymentRequestRecord>;
+    private intentsKey;
+    private readLocalIntents;
+    private writeLocalIntents;
+    private setLocalIntentStatus;
+    /**
+     * Persist a (client-encrypted — S6) intent payload: LOCAL copy first, then
+     * `PUT /v1/intents/{transferId}` and await the server ack (E.3 — the engine
+     * MUST NOT be called before this resolves). A failed server PUT throws, but
+     * the local copy stays as the restore backstop and is re-PUT by
+     * {@link resyncOpenIntents}.
+     */
+    putIntent(transferId: string, payloadEnvelope: string): Promise<void>;
+    /** `GET /v1/intents?status=` — server-side intent list. */
+    listIntents(status: 'open' | 'aborted'): Promise<IntentRecord[]>;
+    /** `POST /v1/intents/{id}/abort` — soft, recoverable (§16). */
+    abortIntent(transferId: string): Promise<void>;
+    /** `POST /v1/intents/{id}/complete` — the uniform client-side close (E.3). */
+    completeIntent(transferId: string): Promise<void>;
+    /** The locally-known open intents (the E.3 restore backstop). */
+    listLocalOpenIntents(): Promise<IntentRecord[]>;
+    /**
+     * Re-PUT every locally-known open intent (idempotent — the server PUT is
+     * write-once while open/completed). Called after a `syncEpoch` change
+     * (server restore — §5.4): intents are the one server table not
+     * re-derivable from blobs.
+     */
+    resyncOpenIntents(): Promise<void>;
+    private syncEpochKey;
+    /**
+     * Track the server `syncEpoch` carried by cursor-bearing responses and
+     * wakes. On a change (server restore), re-PUT locally-known open intents
+     * before anything resumes (E.3). Storage-provider cursor invalidation is
+     * the provider's own duty (S2) — it observes the same epoch values.
+     */
+    private noteSyncEpoch;
+    /**
+     * Open the wake channel: `POST /v1/ws-ticket` (JWT-authed, single-use,
+     * short TTL) then `GET /v1/ws?ticket=…` — the JWT never appears in a URL.
+     * Wakes are nudges only; correctness comes from the `?since=` cursors.
+     */
+    connectWakeSocket(onWake: WakeCallback): Promise<WakeSocketHandle>;
+}
+
+/**
+ * WalletApiTokenStorageProvider — the lazy, thin-wallet storage provider over
+ * the wallet-api backend (sdk-changes S2; ARCHITECTURE §5/§16).
+ *
+ * Platform-neutral (browser + Node) over the injected {@link WalletApiClient}.
+ * The wallet renders balances from the server's value-indexed inventory view;
+ * blobs are fetched on demand only to spend (signed GET URLs). Key behaviors:
+ *
+ * - **Tombstone-aware delta sync** (§5.1): `?since=` deltas include
+ *   `status:'removed'` rows — the only way a stale device learns about
+ *   spends/handoffs; the provider applies them (drops the entries from its
+ *   active view) and loops while `more`.
+ * - **Paginated full pull** is finished with an immediate
+ *   `?since=<page-1 cursor>` closing delta, whose tombstones repair any flips
+ *   that happened between pages (§5.1).
+ * - **`syncEpoch` change** (server restore — §5.4): discard all persisted
+ *   cursors, full pull, then re-PUT locally-known open intents (E.3, via the
+ *   client) before anything resumes.
+ * - **Write-behind with empty-import protection** (§5.1 client guards): a
+ *   removal is pushed only after a successful inventory load and only for a
+ *   confirmed on-chain spend (a `_tombstones` entry) — a fresh device or a
+ *   failed load can never appear to "empty" the wallet, and a merely-absent
+ *   token is never removed.
+ * - **`recoverRemoved()`** (§5.3 recovery): tombstones the client cannot match
+ *   to a known spend are re-fetched via blob-urls (which work for own
+ *   tombstoned rows), re-verified locally, and re-added (reactivation). A
+ *   server `409` is an evidenced tombstone — "actually spent" — and is kept.
+ * - **Blob upload** via upload-urls with client-side sha256; a `412` from the
+ *   content-addressed store means the blob already exists = success (§5.2).
+ */
+
+interface WalletApiTokenStorageConfig {
+    /** The authenticated wallet-api client (S1). DI — never a singleton. */
+    client: WalletApiClient;
+    /** Persists the inventory cursor, syncEpoch and own-spend set per identity. */
+    stateStore: KeyValueStore;
+    /**
+     * Optional local token verification used by `recoverRemoved()` before
+     * re-adding a tombstoned blob (S2: "re-verifies locally"). Wire the engine's
+     * `verify` here at composition; the default accepts any blob that decodes
+     * and matches its tokenId.
+     */
+    verifyToken?: (blob: TokenBlob) => Promise<boolean>;
+}
+declare class WalletApiTokenStorageProvider implements TokenStorageProvider<TxfStorageDataBase> {
+    readonly id = "wallet-api-token-storage";
+    readonly name = "Wallet API Token Storage";
+    readonly type: "cloud";
+    private readonly client;
+    private readonly stateStore;
+    private readonly verifyToken?;
+    private status;
+    private identity;
+    /** Local mirror of the inventory view — active rows and tombstones. */
+    private readonly view;
+    /**
+     * Empty-import protection (§5.1): no removal is ever pushed before this
+     * flips on the first successful inventory load.
+     */
+    private hadSuccessfulLoad;
+    constructor(config: WalletApiTokenStorageConfig);
+    setIdentity(identity: FullIdentity): void;
+    initialize(): Promise<boolean>;
+    shutdown(): Promise<void>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    private stateKey;
+    private readCursor;
+    private readSyncEpoch;
+    private persistSyncState;
+    /** TokenIds this provider itself spent — `recoverRemoved()` skips these. */
+    private readKnownSpends;
+    private addKnownSpends;
+    private applyItems;
+    /** Full pull + the §5.1 closing delta; replaces the whole local view. */
+    private fullPull;
+    /**
+     * Delta loop from the persisted cursor. Returns `true` when the server's
+     * `syncEpoch` no longer matches the persisted one — the cursors are invalid
+     * (server restore, §5.4) and the caller must resync from scratch.
+     */
+    private deltaLoop;
+    /** §5.4: discard cursors → full pull → re-PUT locally-known open intents. */
+    private handleSyncEpochChange;
+    /** Converge the local view with the server (delta when possible). */
+    private syncInventory;
+    /**
+     * Without `since`: converge with the server, then return the full active
+     * view (`more:false`) — a fresh device renders balances with zero blob
+     * downloads. With `since`: a true server delta page (tombstones included),
+     * also applied to the local view.
+     */
+    listInventory(since?: bigint): Promise<InventoryView>;
+    private snapshotView;
+    /** Fetch + decode one blob on demand via a short-lived signed GET (§5.1). */
+    getToken(tokenId: string): Promise<TokenBlob>;
+    /**
+     * The §16 wire serves RAW token bytes (§5.2/§8.2 — the sphere 39051
+     * envelope never crosses the API): re-wrap them for the engine-facing
+     * {@link TokenBlob} surface. Envelope bytes (older rows, fake-world seeds)
+     * still decode — their embedded tokenId is then checked by the caller. The
+     * `network` of a raw wrap is not recoverable without the engine; consumers
+     * derive it from the decoded token (`engine.decodeToken` re-wraps), so it
+     * is never read from this value.
+     */
+    private wrapWireBlob;
+    /**
+     * Record a spend (§5.3) — idempotent by `transferId` server-side. MUST be
+     * called after the mailbox deposit of the same `transferId` (the backend
+     * evidence-checks removals against it). Refreshes the local view from the
+     * resulting delta.
+     */
+    applyDelta(transferId: string, spent: string[], added: ApplyDeltaAdded[], opts?: ApplyDeltaOptions): Promise<void>;
+    /**
+     * Re-add tombstoned tokens this client cannot match to a known spend (a
+     * wiped view — stolen JWT or a buggy client). Blobs are retained server-side
+     * and blob-urls works for own tombstoned rows; each candidate is re-fetched,
+     * locally verified, and re-added (reactivation). A `409` is the server's
+     * verdict that the tombstone is an evidenced spend — kept as spent.
+     */
+    recoverRemoved(): Promise<RecoverRemovedResult>;
+    private fetchRemovedBlob;
+    private locallyValid;
+    /**
+     * Thin view: converges with the server and reports tombstones, but carries
+     * NO token entries — blobs are fetched on demand via `getToken()`
+     * (sdk-changes S2: `load()` no longer eagerly pulls every blob).
+     */
+    load(): Promise<LoadResult<TxfStorageDataBase>>;
+    /**
+     * Write-behind push of a whole-blob snapshot:
+     * - unknown tokens are uploaded (content-addressed, 412 = already present)
+     *   and added via one idempotent apply;
+     * - removals are pushed ONLY for confirmed spends (`_tombstones` entries)
+     *   and ONLY after a successful inventory load (empty-import protection,
+     *   §5.1) — a merely-absent token is never removed.
+     * A failed sync fails the save: pushing against an unknown server view
+     * could only do harm.
+     */
+    save(data: TxfStorageDataBase): Promise<SaveResult>;
+    private pushAdditions;
+    private pushRemovals;
+    sync(localData: TxfStorageDataBase): Promise<SyncResult<TxfStorageDataBase>>;
+}
+declare function createWalletApiTokenStorageProvider(config: WalletApiTokenStorageConfig): WalletApiTokenStorageProvider;
+
+/**
+ * WalletApiMailboxProvider — the reference `DeliveryProvider` implementation
+ * over the wallet-api mailbox (sdk-changes S3/S7; ARCHITECTURE §6/§16).
+ *
+ * Platform-neutral over the injected {@link WalletApiClient}. Key behaviors:
+ *
+ * - **deliver** = sha256 + upload via upload-urls (a `412` from the
+ *   content-addressed store means the blob is already present = success,
+ *   §5.2) → `POST /v1/mailbox` (idempotent by content-derived `entry_id`,
+ *   §6). The memo is encrypted client-side with the S6 field key before it
+ *   leaves the device; the deposit's `entryId` is verified to equal the
+ *   locally computed content-derived id — a backend substituting row ids is a
+ *   protocol violation (covenant §3.1-4).
+ * - **incoming** = `GET /v1/mailbox?since=` paging (`more` loops), yielding
+ *   claimable entries (pending; claimed/rejected entries are recorded as seen
+ *   and skipped — they were resolved here or on another of the owner's
+ *   devices). `fetchBlob` uses the entry's `getUrl` and re-derives
+ *   (tokenId, stateHash, deliveryId) from the actual bytes — the recipient
+ *   never trusts the backend (§8.2). `blobCollected` entries throw a typed
+ *   error.
+ * - **ack** → claim with the provider's **composition-time custody**
+ *   (`'inventory'` → `intoInventory: true` handoff; `'external'` →
+ *   `intoInventory: false`, ZERO inventory writes — §6 delivery-only claim),
+ *   or reject (terminal for discovery only — §6).
+ * - **Persistent seen-set**: every acked delivery's content-derived id — the
+ *   canonical hash of its `(tokenId, stateHash)` pair — is persisted via the
+ *   injected {@link KeyValueStore}; a replayed delivery (server replay, cursor
+ *   reset, restore) is never yielded again (S7 port contract).
+ */
+
+interface WalletApiMailboxProviderConfig {
+    /** The authenticated wallet-api client (S1). DI — never a singleton. */
+    client: WalletApiClient;
+    /**
+     * Composition-time custody (S7 — NEVER a per-call flag): `'inventory'` for
+     * the full wallet-api preset (acks hand tokens into the server inventory),
+     * `'external'` for the own-storage preset (acks perform zero inventory
+     * writes; the app's storage keeps custody).
+     */
+    custody: DeliveryCustody;
+    /** Persists the per-identity seen-set + mailbox cursor. */
+    stateStore: KeyValueStore;
+    /**
+     * The backend-true (tokenId, stateHash) derivation (`ITokenEngine.deliveryKeys`).
+     * Optional at construction — compositions are engine-less; `PaymentsModule`
+     * late-binds it via `bindDeliveryKeys` at init. The provider never derives
+     * these locally (§8.2 / sdk-changes S7) and fails loudly if unbound.
+     */
+    deliveryKeys?: (blobBytes: Uint8Array) => Promise<{
+        tokenId: string;
+        stateHash: string;
+    }>;
+}
+declare class WalletApiMailboxProvider implements DeliveryProvider {
+    readonly custody: DeliveryCustody;
+    private readonly client;
+    private readonly stateStore;
+    private deriveKeysFn;
+    private identity;
+    private fieldKey;
+    constructor(config: WalletApiMailboxProviderConfig);
+    /** @inheritDoc — wired by PaymentsModule at init (engine-owning seam). */
+    bindDeliveryKeys(derive: (blobBytes: Uint8Array) => Promise<{
+        tokenId: string;
+        stateHash: string;
+    }>): void;
+    private deriveKeys;
+    /** Bind the wallet identity (derives the S6 field key; binds the client). */
+    setIdentity(identity: {
+        privateKey: string;
+        chainPubkey: string;
+    }): void;
+    private stateKey;
+    /**
+     * The persistent seen-set (S7): content-derived delivery ids — i.e. the
+     * canonical `SHA-256(tokenId ‖ stateHash)` encoding of the (tokenId,
+     * stateHash) pairs this wallet has already resolved.
+     */
+    private readSeen;
+    private addSeen;
+    private readCursorState;
+    private persistCursorState;
+    /**
+     * Idempotent per (token, state): the upload is content-addressed (412 =
+     * already present = success — §5.2) and the deposit is idempotent by the
+     * content-derived entry_id — it succeeds even after the recipient claimed
+     * (§6), which is what makes the sender's journal replay safe.
+     */
+    deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
+    /**
+     * Pull entries since the given cursor (or the persisted one), loop while
+     * `more`, and yield claimable deliveries not yet in the seen-set. The
+     * persisted cursor advances to the server's read pointer (§6) — entries at
+     * or below it are all resolved; the seen-set (not the cursor) is the replay
+     * guard, so a cursor reset is safe.
+     */
+    incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    private toIncomingDelivery;
+    ack(deliveryId: string, disposition: DeliveryDisposition): Promise<void>;
+    onWake(callback: () => void): () => void;
+}
+declare function createWalletApiMailboxProvider(config: WalletApiMailboxProviderConfig): WalletApiMailboxProvider;
+
+/**
+ * impl/shared/wallet-api/composition.ts — port composition (sdk-changes S4/S7,
+ * covenant §3.1-6).
+ *
+ * The Sphere frontend is a VIEW: all I/O sits behind three independently
+ * swappable ports — storage (`TokenStorageProvider`), delivery
+ * (`DeliveryProvider`) and the engine/aggregator config (`OracleProvider`) —
+ * selected at composition time. wallet-api ships as ONE implementation of each
+ * port, not as the port:
+ *
+ * - {@link createSphereProviders} — the composition root: take any platform
+ *   base bundle (`createBrowserProviders` / `createNodeProviders`) and select
+ *   each port independently.
+ * - {@link createWalletApiProviders} — the FULL wallet-api preset: thin
+ *   storage (server inventory custody) + mailbox delivery with custody
+ *   `'inventory'`.
+ * - {@link createOwnStorageWalletApiProviders} — the delivery-only preset:
+ *   the app's own (local) storage keeps custody; the mailbox provider is
+ *   constructed with custody `'external'`, so every ack sends
+ *   `intoInventory: false` — zero server inventory writes by construction
+ *   (ARCHITECTURE §6 delivery-only claim; never a per-call flag).
+ *
+ * Asset-transport routing (S4): composing a delivery port moves ASSETS to it;
+ * messaging, group chat and nametag bindings stay on the Nostr transport in
+ * the base bundle. Payment requests ride wallet-api whenever the `walletApi`
+ * client these presets return is passed to `Sphere.init` — `PaymentsModule`
+ * detects the §16 payment-request capability on it and does not install the
+ * Nostr payment-request channel (sdk-changes S4).
+ */
+
+/** The minimum any platform base bundle provides (browser/node factories do). */
+interface SphereBaseProviders {
+    storage: StorageProvider;
+    transport: TransportProvider;
+    oracle: OracleProvider;
+    tokenStorage: TokenStorageProvider<TxfStorageDataBase>;
+}
+/** Independent port selection (sdk-changes S7): any combination is legal. */
+interface SphereProviderPorts {
+    /** Storage port override (token inventory + blob custody). */
+    storage?: TokenStorageProvider<TxfStorageDataBase>;
+    /** Delivery port (assets move to it; messaging stays on the base transport). */
+    delivery?: DeliveryProvider;
+    /** Engine/aggregator config port override. */
+    engine?: OracleProvider;
+}
+/**
+ * Compose a Sphere provider bundle with each port selected independently
+ * (covenant §3.1-6). Unselected ports keep the base bundle's implementation.
+ */
+declare function createSphereProviders<B extends SphereBaseProviders>(base: B, ports?: SphereProviderPorts): B & {
+    delivery?: DeliveryProvider;
+};
+interface WalletApiCompositionConfig {
+    /** Backend base URL — https off-loopback (ARCHITECTURE §4, client-enforced). */
+    baseUrl: string;
+    /** Network name (e.g. 'testnet2') — required end-to-end (ARCHITECTURE §14). */
+    network: string;
+    /**
+     * Stable per-device label (ARCHITECTURE §4 — one session row per (owner,
+     * device); the refresh token is stored under it). Pass a persisted value;
+     * when omitted a fresh random label is generated per construction, which
+     * still works but starts every run with a challenge sign-in.
+     */
+    deviceId?: string;
+    /** Reuse an existing client (tests / advanced wiring). */
+    client?: WalletApiClient;
+    /** Refresh-token / cursor / seen-set persistence; defaults to `base.storage`. */
+    stateStore?: KeyValueStore;
+    /** Injectable fetch (defaults to `globalThis.fetch`). */
+    fetchFn?: FetchLike;
+    /** Injectable WebSocket factory (defaults to `globalThis.WebSocket`). */
+    webSocketFactory?: WebSocketFactoryLike;
+    /** Local token verification for `recoverRemoved()` (wire the engine here). */
+    verifyToken?: (blob: TokenBlob) => Promise<boolean>;
+}
+/** What the wallet-api presets add to the base bundle. */
+interface WalletApiProviderExtras {
+    delivery: DeliveryProvider;
+    /** The S1 client — pass to `Sphere.init({ walletApi })` for the S4 auth lifecycle. */
+    walletApi: WalletApiClient;
+}
+/**
+ * The FULL wallet-api preset (S4): wallet-api keeps inventory custody —
+ * thin/lazy storage over the server's value index + mailbox delivery with
+ * custody `'inventory'` (claims perform the §6 ownership handoff).
+ */
+declare function createWalletApiProviders<B extends SphereBaseProviders>(base: B, config: WalletApiCompositionConfig): B & WalletApiProviderExtras;
+/**
+ * The OWN-STORAGE preset (S7: own storage + wallet-api delivery — a
+ * supported, tested composition): the base bundle's local storage keeps
+ * custody; wallet-api is purely the delivery rail. Custody `'external'` is
+ * baked in at construction — every ack sends `intoInventory: false`, so a
+ * recipient's claim performs ZERO inventory writes even when `ack` is called
+ * with no thought given to options (sdk-changes S7). Senders never call
+ * apply; their sends close via `intents/{id}/complete` alone (ARCHITECTURE
+ * §6 storage-opt-out senders), which the wallet-api client (passed as
+ * `walletApi`) provides.
+ */
+declare function createOwnStorageWalletApiProviders<B extends SphereBaseProviders>(base: B, config: WalletApiCompositionConfig): B & WalletApiProviderExtras;
+
+export { type SphereBaseProviders, type SphereProviderPorts, type WalletApiCompositionConfig, WalletApiMailboxProvider, type WalletApiMailboxProviderConfig, type WalletApiProviderExtras, type WalletApiTokenStorageConfig, WalletApiTokenStorageProvider, createOwnStorageWalletApiProviders, createSphereProviders, createWalletApiMailboxProvider, createWalletApiProviders, createWalletApiTokenStorageProvider };