@miden-sdk/react 0.13.2 → 0.13.3

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { AccountStorageMode, Account, AccountHeader, AccountId, TransactionRequest, WebClient, AccountFile, InputNoteRecord, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver } from '@miden-sdk/miden-sdk';
+import { AccountStorageMode, AccountComponent, Account, AccountHeader, AccountId, TransactionRequest, WebClient, AccountFile, InputNoteRecord, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver, NoteAttachment } from '@miden-sdk/miden-sdk';
 export { Account, AccountFile, AccountHeader, AccountId, AccountStorageMode, ConsumableNoteRecord, InputNoteRecord, NoteType, TransactionFilter, TransactionId, TransactionRecord, TransactionRequest, WebClient } from '@miden-sdk/miden-sdk';
 
 declare module "@miden-sdk/miden-sdk" {
@@ -38,6 +38,8 @@ interface SignerAccountConfig {
     storageMode: AccountStorageMode;
     /** Optional seed for deterministic account ID */
     accountSeed?: Uint8Array;
+    /** Optional custom account components to include in the account (e.g. from a compiled .masp package) */
+    customComponents?: AccountComponent[];
 }
 /**
  * Context value provided by signer providers (Para, Turnkey, MidenFi, etc.).
@@ -161,6 +163,10 @@ interface AssetBalance {
 interface NotesFilter {
     status?: "all" | "consumed" | "committed" | "expected" | "processing";
     accountId?: string;
+    /** Only notes from this sender (any format, normalized internally) */
+    sender?: string;
+    /** Exclude these note IDs */
+    excludeIds?: string[];
 }
 interface NotesResult {
     notes: InputNoteRecord[];
@@ -249,20 +255,30 @@ interface SendOptions {
     to: string;
     /** Asset ID to send (token id) */
     assetId: string;
-    /** Amount to send */
-    amount: bigint;
+    /** Amount to send (ignored when sendAll is true) */
+    amount?: bigint;
     /** Note type. Default: private */
-    noteType?: "private" | "public" | "encrypted";
+    noteType?: "private" | "public";
     /** Block height after which sender can reclaim note */
     recallHeight?: number;
     /** Block height after which recipient can consume note */
     timelockHeight?: number;
+    /** Arbitrary data payload attached to the note */
+    attachment?: bigint[] | Uint8Array | number[];
+    /** Skip auto-sync before send. Default: false */
+    skipSync?: boolean;
+    /** Send the full balance of this asset. When true, amount is ignored. */
+    sendAll?: boolean;
 }
 interface MultiSendRecipient {
     /** Recipient account ID */
     to: string;
     /** Amount to send */
     amount: bigint;
+    /** Per-recipient note type override */
+    noteType?: "private" | "public";
+    /** Per-recipient attachment */
+    attachment?: bigint[] | Uint8Array | number[];
 }
 interface MultiSendOptions {
     /** Sender account ID */
@@ -271,8 +287,10 @@ interface MultiSendOptions {
     assetId: string;
     /** Recipient list */
     recipients: MultiSendRecipient[];
-    /** Note type. Default: private */
-    noteType?: "private" | "public" | "encrypted";
+    /** Default note type for all recipients. Default: private */
+    noteType?: "private" | "public";
+    /** Skip auto-sync before send. Default: false */
+    skipSync?: boolean;
 }
 interface InternalTransferOptions {
     /** Sender account ID */
@@ -284,7 +302,7 @@ interface InternalTransferOptions {
     /** Amount to transfer */
     amount: bigint;
     /** Note type. Default: private */
-    noteType?: "private" | "public" | "encrypted";
+    noteType?: "private" | "public";
 }
 interface InternalTransferChainOptions {
     /** Initial sender account ID */
@@ -296,7 +314,7 @@ interface InternalTransferChainOptions {
     /** Amount to transfer per hop */
     amount: bigint;
     /** Note type. Default: private */
-    noteType?: "private" | "public" | "encrypted";
+    noteType?: "private" | "public";
 }
 interface InternalTransferResult {
     createTransactionId: string;
@@ -327,7 +345,7 @@ interface MintOptions {
     /** Amount to mint */
     amount: bigint;
     /** Note type. Default: private */
-    noteType?: "private" | "public" | "encrypted";
+    noteType?: "private" | "public";
 }
 interface ConsumeOptions {
     /** Account ID that will consume the notes */
@@ -347,19 +365,99 @@ interface SwapOptions {
     /** Amount being requested */
     requestedAmount: bigint;
     /** Note type for swap note. Default: private */
-    noteType?: "private" | "public" | "encrypted";
+    noteType?: "private" | "public";
     /** Note type for payback note. Default: private */
-    paybackNoteType?: "private" | "public" | "encrypted";
+    paybackNoteType?: "private" | "public";
 }
 interface ExecuteTransactionOptions {
     /** Account ID the transaction applies to */
     accountId: string | AccountId;
     /** Transaction request or builder */
     request: TransactionRequest | ((client: WebClient) => TransactionRequest | Promise<TransactionRequest>);
+    /** Skip auto-sync before transaction. Default: false */
+    skipSync?: boolean;
 }
 interface TransactionResult {
     transactionId: string;
 }
+interface StreamedNote {
+    /** Note ID (hex string) */
+    id: string;
+    /** Sender account ID (bech32 if available) */
+    sender: string;
+    /** First fungible asset amount (convenience; 0n if no fungible assets) */
+    amount: bigint;
+    /** All assets on the note */
+    assets: NoteAsset[];
+    /** The underlying InputNoteRecord for escape-hatch access */
+    record: InputNoteRecord;
+    /** Timestamp (ms) when this note was first observed by the SDK */
+    firstSeenAt: number;
+    /** Pre-decoded attachment values, or null if no attachment */
+    attachment: bigint[] | null;
+}
+interface UseNoteStreamOptions {
+    /** Note status filter. Default: "committed" */
+    status?: "all" | "consumed" | "committed" | "expected" | "processing";
+    /** Only notes from this sender (any format, normalized internally) */
+    sender?: string | null;
+    /** Only notes first seen after this timestamp */
+    since?: number;
+    /** Exclude these note IDs (for cross-phase stale filtering) */
+    excludeIds?: Set<string> | string[];
+    /** Filter by primary asset amount */
+    amountFilter?: (amount: bigint) => boolean;
+}
+interface UseNoteStreamReturn {
+    /** Notes matching all filter criteria */
+    notes: StreamedNote[];
+    /** Most recent note (convenience) */
+    latest: StreamedNote | null;
+    /** Mark a note as handled (excluded from future renders) */
+    markHandled: (noteId: string) => void;
+    /** Mark all current notes as handled */
+    markAllHandled: () => void;
+    /** Snapshot current state for passing to next phase */
+    snapshot: () => {
+        ids: Set<string>;
+        timestamp: number;
+    };
+    isLoading: boolean;
+    error: Error | null;
+}
+interface UseSessionAccountOptions {
+    /** Callback to fund the session wallet. Receives the session wallet ID. */
+    fund: (sessionAccountId: string) => Promise<void>;
+    /** Asset ID of the funding token (reserved for future filtering of consumable notes) */
+    assetId?: string;
+    /** Wallet creation options */
+    walletOptions?: {
+        storageMode?: "private" | "public";
+        mutable?: boolean;
+        authScheme?: 0 | 1;
+    };
+    /** Polling interval for funding note detection (ms). Default: 3000 */
+    pollIntervalMs?: number;
+    /** Maximum time to wait for funding note (ms). Default: 60000 */
+    maxWaitMs?: number;
+    /** localStorage key prefix for persistence. Default: "miden-session" */
+    storagePrefix?: string;
+}
+type SessionAccountStep = "idle" | "creating" | "funding" | "consuming" | "ready";
+interface UseSessionAccountReturn {
+    /** Start the create->fund->consume flow */
+    initialize: () => Promise<void>;
+    /** Session wallet ID (bech32), or null if not yet created */
+    sessionAccountId: string | null;
+    /** Whether the session wallet is funded and ready */
+    isReady: boolean;
+    /** Current step */
+    step: SessionAccountStep;
+    /** Error from any step */
+    error: Error | null;
+    /** Clear all session data and reset */
+    reset: () => void;
+}
 declare const DEFAULTS: {
     readonly RPC_URL: undefined;
     readonly AUTO_SYNC_INTERVAL: 15000;
@@ -487,6 +585,34 @@ declare function useAccount(accountId: string | AccountId | undefined): AccountR
  */
 declare function useNotes(options?: NotesFilter): NotesResult;
 
+/**
+ * Hook for temporal note tracking with a unified model.
+ *
+ * Replaces the common pattern of `handledNoteIds` refs, deferred baselines,
+ * and dual-track note decoding. Returns `StreamedNote` objects that merge
+ * summary data with the underlying record and pre-decode attachments.
+ *
+ * @example
+ * ```tsx
+ * function IncomingNotes({ opponentId }: { opponentId: string }) {
+ *   const { notes, latest, markHandled, snapshot } = useNoteStream({
+ *     sender: opponentId,
+ *     status: "committed",
+ *   });
+ *
+ *   useEffect(() => {
+ *     if (latest) {
+ *       console.log("New note!", latest.attachment);
+ *       markHandled(latest.id);
+ *     }
+ *   }, [latest, markHandled]);
+ *
+ *   return <div>{notes.length} unhandled notes</div>;
+ * }
+ * ```
+ */
+declare function useNoteStream(options?: UseNoteStreamOptions): UseNoteStreamReturn;
+
 /**
  * Hook to query transaction history and track transaction state.
  *
@@ -992,6 +1118,37 @@ interface UseTransactionResult {
  */
 declare function useTransaction(): UseTransactionResult;
 
+/**
+ * Hook to manage a session wallet lifecycle: create -> fund -> consume.
+ *
+ * Replaces the common 300+ line pattern of creating a temporary wallet,
+ * waiting for funding, and consuming the funding note.
+ *
+ * @example
+ * ```tsx
+ * function SessionWallet() {
+ *   const { initialize, sessionAccountId, isReady, step, error, reset } =
+ *     useSessionAccount({
+ *       fund: async (sessionId) => {
+ *         // Send tokens from main wallet to session wallet
+ *         await send({ from: mainWalletId, to: sessionId, assetId, amount: 100n });
+ *       },
+ *       assetId: "0x...",
+ *     });
+ *
+ *   if (error) return <div>Error: {error.message} <button onClick={reset}>Retry</button></div>;
+ *   if (isReady) return <div>Session ready: {sessionAccountId}</div>;
+ *
+ *   return (
+ *     <button onClick={initialize} disabled={step !== "idle"}>
+ *       {step === "idle" ? "Start Session" : step}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useSessionAccount(options: UseSessionAccountOptions): UseSessionAccountReturn;
+
 declare const toBech32AccountId: (accountId: string) => string;
 
 declare const formatAssetAmount: (amount: bigint, decimals?: number) => string;
@@ -1000,4 +1157,99 @@ declare const parseAssetAmount: (input: string, decimals?: number) => bigint;
 declare const getNoteSummary: (note: ConsumableNoteRecord | InputNoteRecord, getAssetMetadata?: (assetId: string) => AssetMetadata | undefined) => NoteSummary | null;
 declare const formatNoteSummary: (summary: NoteSummary, formatAsset?: (asset: NoteAsset) => string) => string;
 
-export { type AccountResult, type AccountsResult, type AssetBalance, type AssetMetadata, type ConsumeOptions, type CreateFaucetOptions, type CreateWalletOptions, DEFAULTS, type ExecuteTransactionOptions, type ImportAccountOptions, type InternalTransferChainOptions, type InternalTransferOptions, type InternalTransferResult, type MidenConfig, MidenProvider, type MidenState, type MintOptions, type MultiSendOptions, type MultiSendRecipient, type MutationResult, type NoteAsset, type NoteSummary, type NotesFilter, type NotesResult, type ProverConfig, type ProverUrls, type QueryResult, type RpcUrlConfig, type SendOptions, type SignCallback, type SignerAccountConfig, type SignerAccountType, SignerContext, type SignerContextValue, type SwapOptions, type SyncState, type TransactionHistoryOptions, type TransactionHistoryResult, type TransactionResult, type TransactionStage, type TransactionStatus, type UseConsumeResult, type UseCreateFaucetResult, type UseCreateWalletResult, type UseImportAccountResult, type UseInternalTransferResult, type UseMintResult, type UseMultiSendResult, type UseSendResult, type UseSwapResult, type UseSyncStateResult, type UseTransactionHistoryResult, type UseTransactionResult, type UseWaitForCommitResult, type UseWaitForNotesResult, type WaitForCommitOptions, type WaitForNotesOptions, formatAssetAmount, formatNoteSummary, getNoteSummary, parseAssetAmount, toBech32AccountId, useAccount, useAccounts, useAssetMetadata, useConsume, useCreateFaucet, useCreateWallet, useImportAccount, useInternalTransfer, useMiden, useMidenClient, useMint, useMultiSend, useNotes, useSend, useSigner, useSwap, useSyncState, useTransaction, useTransactionHistory, useWaitForCommit, useWaitForNotes };
+/**
+ * Normalize any account ID format (hex, bech32, 0x-prefixed) to bech32.
+ * Returns the original string if conversion fails.
+ */
+declare function normalizeAccountId(id: string): string;
+/**
+ * Compare two account IDs for equality regardless of format (hex vs bech32).
+ * Parses both to AccountId objects and compares their hex representations.
+ */
+declare function accountIdsEqual(a: string, b: string): boolean;
+
+interface NoteAttachmentData {
+    values: bigint[];
+    kind: "word" | "array";
+}
+/**
+ * Decode a note's attachment. Returns null if no attachment.
+ */
+declare function readNoteAttachment(note: InputNoteRecord): NoteAttachmentData | null;
+/**
+ * Encode values into a NoteAttachment.
+ * <= 4 values -> Word (avoids miden-standards 0.13.x Array advice-map bug).
+ * > 4 values -> Array.
+ *
+ * Note: Values are padded to word boundaries (multiples of 4) with trailing 0n.
+ * `readNoteAttachment` returns raw values including padding. Consumers should
+ * strip trailing zeros if they need the original unpadded values.
+ */
+declare function createNoteAttachment(values: bigint[] | Uint8Array | number[]): NoteAttachment;
+
+declare function bytesToBigInt(bytes: Uint8Array): bigint;
+declare function bigIntToBytes(value: bigint, length: number): Uint8Array;
+declare function concatBytes(...arrays: Uint8Array[]): Uint8Array;
+
+type MidenErrorCode = "WASM_CLASS_MISMATCH" | "WASM_POINTER_CONSUMED" | "WASM_NOT_INITIALIZED" | "WASM_SYNC_REQUIRED" | "SEND_BUSY" | "OPERATION_BUSY" | "UNKNOWN";
+declare class MidenError extends Error {
+    readonly code: MidenErrorCode;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        code?: MidenErrorCode;
+    });
+}
+declare function wrapWasmError(e: unknown): Error;
+
+/** Minimal adapter shape (duck-typed, no dependency on wallet-adapter-base) */
+interface WalletAdapterLike {
+    readyState: string;
+    on(event: "readyStateChange", cb: (state: string) => void): void;
+    off(event: "readyStateChange", cb: (state: string) => void): void;
+}
+/**
+ * Wait for a wallet adapter to reach "Installed" readyState.
+ * Returns immediately if already installed. Otherwise listens
+ * for readyStateChange events with a timeout.
+ *
+ * @example
+ * ```ts
+ * const adapter = wallets[0].adapter;
+ * await waitForWalletDetection(adapter);        // default 5s timeout
+ * await waitForWalletDetection(adapter, 10000); // 10s timeout
+ * ```
+ */
+declare function waitForWalletDetection(adapter: WalletAdapterLike, timeoutMs?: number): Promise<void>;
+
+interface MigrateStorageOptions {
+    /** Current version string to compare against stored version */
+    version: string;
+    /** localStorage key for version tracking. Default: "miden:storageVersion" */
+    versionKey?: string;
+    /** Callback before clearing storage (e.g., to save data) */
+    onBeforeClear?: () => void | Promise<void>;
+    /** Reload page after clearing. Default: true */
+    reloadOnClear?: boolean;
+}
+/**
+ * Check if stored version matches current version. If not, clear Miden IndexedDB
+ * databases and localStorage, then optionally reload.
+ * Returns true if migration was triggered.
+ */
+declare function migrateStorage(options: MigrateStorageOptions): Promise<boolean>;
+/**
+ * Clear all Miden-related IndexedDB databases.
+ */
+declare function clearMidenStorage(): Promise<void>;
+/**
+ * Create a namespaced localStorage helper for app state persistence.
+ */
+declare function createMidenStorage(prefix: string): {
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+    clear(): void;
+};
+
+export { type AccountResult, type AccountsResult, type AssetBalance, type AssetMetadata, type ConsumeOptions, type CreateFaucetOptions, type CreateWalletOptions, DEFAULTS, type ExecuteTransactionOptions, type ImportAccountOptions, type InternalTransferChainOptions, type InternalTransferOptions, type InternalTransferResult, type MidenConfig, MidenError, type MidenErrorCode, MidenProvider, type MidenState, type MigrateStorageOptions, type MintOptions, type MultiSendOptions, type MultiSendRecipient, type MutationResult, type NoteAsset, type NoteAttachmentData, type NoteSummary, type NotesFilter, type NotesResult, type ProverConfig, type ProverUrls, type QueryResult, type RpcUrlConfig, type SendOptions, type SessionAccountStep, type SignCallback, type SignerAccountConfig, type SignerAccountType, SignerContext, type SignerContextValue, type StreamedNote, type SwapOptions, type SyncState, type TransactionHistoryOptions, type TransactionHistoryResult, type TransactionResult, type TransactionStage, type TransactionStatus, type UseConsumeResult, type UseCreateFaucetResult, type UseCreateWalletResult, type UseImportAccountResult, type UseInternalTransferResult, type UseMintResult, type UseMultiSendResult, type UseNoteStreamOptions, type UseNoteStreamReturn, type UseSendResult, type UseSessionAccountOptions, type UseSessionAccountReturn, type UseSwapResult, type UseSyncStateResult, type UseTransactionHistoryResult, type UseTransactionResult, type UseWaitForCommitResult, type UseWaitForNotesResult, type WaitForCommitOptions, type WaitForNotesOptions, type WalletAdapterLike, accountIdsEqual, bigIntToBytes, bytesToBigInt, clearMidenStorage, concatBytes, createMidenStorage, createNoteAttachment, formatAssetAmount, formatNoteSummary, getNoteSummary, migrateStorage, normalizeAccountId, parseAssetAmount, readNoteAttachment, toBech32AccountId, useAccount, useAccounts, useAssetMetadata, useConsume, useCreateFaucet, useCreateWallet, useImportAccount, useInternalTransfer, useMiden, useMidenClient, useMint, useMultiSend, useNoteStream, useNotes, useSend, useSessionAccount, useSigner, useSwap, useSyncState, useTransaction, useTransactionHistory, useWaitForCommit, useWaitForNotes, waitForWalletDetection, wrapWasmError };