@aztec-labs/wallet-sdk 6.0.0-nightly.20260829

package/README.md

@@ -0,0 +1,478 @@
+# Wallet SDK Integration Guide for Third-Party Wallet Developers
+
+This guide explains how to integrate your wallet with the Aztec Wallet SDK, enabling dApps to discover and interact with your wallet implementation.
+
+## Available Types
+
+All types and utilities needed for wallet integration are exported from `@aztec-labs/wallet-sdk/types`:
+
+```typescript
+import type {
+  DiscoveryRequest,
+  DiscoveryResponse,
+  KeyExchangeRequest,
+  KeyExchangeResponse,
+  WalletInfo,
+  WalletMessage,
+  WalletResponse,
+} from '@aztec-labs/wallet-sdk/types';
+```
+
+Cryptographic utilities for secure channel establishment are exported from `@aztec-labs/wallet-sdk/crypto`:
+
+```typescript
+import type { EncryptedPayload, ExportedPublicKey } from '@aztec-labs/wallet-sdk/crypto';
+import {
+  decrypt,
+  deriveSessionKeys,
+  encrypt,
+  exportPublicKey,
+  generateKeyPair,
+  hashToEmoji,
+  importPublicKey,
+} from '@aztec-labs/wallet-sdk/crypto';
+```
+
+**For extension wallets**, pre-built connection handlers are available:
+
+```typescript
+import {
+  BackgroundConnectionHandler,
+  ContentScriptConnectionHandler,
+} from '@aztec-labs/wallet-sdk/extension/handlers';
+```
+
+## Overview
+
+The Wallet SDK uses a **two-phase connection model** with **end-to-end encryption**:
+
+### Phase 1: Discovery
+
+1. **dApp broadcasts** a discovery request with chain information (NO public keys)
+2. **Your wallet shows** a pending connection request to the user
+3. **User approves** the connection request
+4. **Your wallet responds** with basic wallet info and a MessagePort
+
+### Phase 2: Secure Channel Establishment
+
+5. **dApp initiates key exchange** by sending its ECDH public key over the MessagePort
+6. **Wallet generates** ephemeral key pair and derives session keys using HKDF
+7. **Both parties compute** the same verification hash independently
+8. **User verifies** the has matches on both sides. A util for conversion to an emoji grid is provided
+9. **User confirms** the connection in the dApp
+10. **All subsequent communication** is encrypted using AES-256-GCM
+
+### Key Security Features
+
+- **User approval required**: Wallet never reveals itself without explicit user consent
+- **Ephemeral keys**: New key pairs generated for each session
+- **Anti-MITM verification**: 3x3 emoji grid (72 bits of security) for visual confirmation
+
+## Architecture for Extension Wallets
+
+```
+┌─────────────┐    window.postMessage    ┌─────────────────┐    browser.runtime   ┌──────────────────┐
+│   dApp      │◄──(discovery + port)────►│  Content Script │◄────────────────────►│ Background Script│
+│ (web page)  │                          │  (message relay)│                      │ (crypto+state)   │
+└─────────────┘                          └─────────────────┘                      └──────────────────┘
+       │                                          │
+       │              MessagePort                 │
+       └──────────(key exchange + encrypted)──────┘
+```
+
+**Security model:**
+
+- The MessagePort is transferred via `window.postMessage` - other scripts on the page could intercept it
+- **Security comes from encryption**: After key exchange, all communication is AES-256-GCM encrypted
+- Content script never has access to private keys or session secrets
+- All cryptographic operations happen in the background script (service worker)
+- Anti-MITM verification (emoji grid) ensures both parties derived the same keys
+
+## Using Pre-built Connection Handlers
+
+The SDK provides `BackgroundConnectionHandler` and `ContentScriptConnectionHandler` to handle the connection flow. These are the recommended way to build extension wallets.
+
+### Background Script Setup
+
+```typescript
+import {
+  BackgroundConnectionHandler,
+  type BackgroundConnectionConfig,
+  type BackgroundConnectionCallbacks,
+  type BackgroundTransport,
+} from '@aztec-labs/wallet-sdk/extension/handlers';
+import { hashToEmoji } from '@aztec-labs/wallet-sdk/crypto';
+
+// Configuration for your wallet
+const config: BackgroundConnectionConfig = {
+  walletId: 'my-aztec-wallet',
+  walletName: 'My Aztec Wallet',
+  walletVersion: '1.0.0',
+  walletIcon: 'https://example.com/icon.png',
+};
+
+// Transport for browser extension APIs
+const transport: BackgroundTransport = {
+  sendToTab: (tabId, message) => browser.tabs.sendMessage(tabId, message),
+  addContentListener: (handler) => browser.runtime.onMessage.addListener(handler),
+};
+
+// Event callbacks (all optional)
+const callbacks: BackgroundConnectionCallbacks = {
+  // Called when a new discovery request is received
+  onPendingDiscovery: (discovery) => {
+    // Show pending connection in wallet UI
+    // Check if wallet supports this network (chainId AND version)
+    const supported = supportedNetworks.some(
+      n => n.chainId === discovery.chainInfo.chainId.toString() &&
+           n.version === discovery.chainInfo.version.toString()
+    );
+    if (supported) {
+      // Show the user so they can approve or reject
+    }
+  },
+
+  // Called when key exchange completes and session is ready
+  onSessionEstablished: (session) => {
+    // Display verification emojis for user reference
+    console.log('Session emojis:', hashToEmoji(session.verificationHash));
+  },
+
+  // Called when a session is terminated
+  onSessionTerminated: (requestId) => {
+    console.log('Session terminated:', requestId);
+  },
+
+  // Called when a decrypted wallet message is received
+  onWalletMessage: (session, message) => {
+    // Forward to your wallet backend
+    wallet.postMessage(message);
+  },
+};
+
+const handler = new BackgroundConnectionHandler(config, transport, callbacks);
+
+// Initialize the handler to start listening
+handler.initialize();
+
+// User approves connection from wallet UI
+function approveConnection(requestId: string) {
+  handler.approveDiscovery(requestId);
+}
+
+// User denies connection
+function denyConnection(requestId: string) {
+  handler.rejectDiscovery(requestId);
+}
+
+// Send response back to dApp
+async function sendWalletResponse(requestId: string, response: WalletResponse) {
+  await handler.sendResponse(requestId, response);
+}
+
+// Clean up on tab close/navigate
+browser.tabs.onRemoved.addListener((tabId) => {
+  handler.terminateForTab(tabId);
+});
+```
+
+### Content Script Setup
+
+```typescript
+import {
+  ContentScriptConnectionHandler,
+  type ContentScriptTransport,
+} from '@aztec-labs/wallet-sdk/extension/handlers';
+
+const transport: ContentScriptTransport = {
+  sendToBackground: (message) => browser.runtime.sendMessage(message),
+  addBackgroundListener: (handler) => browser.runtime.onMessage.addListener(handler),
+};
+
+const handler = new ContentScriptConnectionHandler(transport);
+
+// Start listening for discovery requests and background messages
+handler.start();
+```
+
+## Testing Your Integration (dApp Side)
+
+The `WalletManager` supports two patterns for consuming discovered wallets.
+
+### Async Iterator Pattern
+
+```typescript
+import { Fr } from '@aztec-labs/foundation/fields';
+import { WalletManager } from '@aztec-labs/wallet-sdk/manager';
+import { hashToEmoji } from '@aztec-labs/wallet-sdk/crypto';
+
+const discovery = WalletManager.configure({
+  extensions: { enabled: true },
+}).getAvailableWallets({
+  chainInfo: {
+    chainId: new Fr(31337),
+    version: new Fr(1),
+  },
+  appId: 'my-dapp',
+  timeout: 60000,
+});
+
+// Iterate over discovered wallets as they're approved
+for await (const provider of discovery.wallets) {
+  console.log(`Found: ${provider.name}`);
+
+  // Establish secure channel (key exchange)
+  const pending = await provider.establishSecureChannel('my-dapp');
+
+  // Display verification emojis to user
+  const emojis = hashToEmoji(pending.verificationHash);
+  console.log('Verify this matches your wallet:', emojis);
+
+  // User confirms emojis match
+  const wallet = await pending.confirm();
+
+  // All calls are now encrypted
+  const accounts = await wallet.getAccounts();
+  console.log('Accounts:', accounts);
+}
+
+// Cancel discovery when done or on cleanup
+discovery.cancel();
+```
+
+### Callback Pattern
+
+```typescript
+import { Fr } from '@aztec-labs/foundation/fields';
+import { WalletManager, type WalletProvider } from '@aztec-labs/wallet-sdk/manager';
+import { hashToEmoji } from '@aztec-labs/wallet-sdk/crypto';
+
+const discoveredProviders: WalletProvider[] = [];
+
+const discovery = WalletManager.configure({
+  extensions: { enabled: true },
+}).getAvailableWallets({
+  chainInfo: {
+    chainId: new Fr(31337),
+    version: new Fr(1),
+  },
+  appId: 'my-dapp',
+  timeout: 60000,
+  // Callback fires as each wallet is discovered
+  onWalletDiscovered: (provider) => {
+    discoveredProviders.push(provider);
+    updateUI(); // Your UI update function
+  },
+});
+
+// Wait for discovery to complete (or cancel early with discovery.cancel())
+await discovery.done;
+console.log('Discovery complete, found:', discoveredProviders.length);
+
+// Connect to a selected provider
+async function connectToWallet(provider: WalletProvider) {
+  const pending = await provider.establishSecureChannel('my-dapp');
+
+  // Show verification UI
+  const emojis = hashToEmoji(pending.verificationHash);
+  showVerificationDialog(emojis);
+
+  // User confirms
+  const wallet = await pending.confirm();
+  return wallet;
+}
+```
+
+### React Hook Example
+
+```typescript
+function useWalletDiscovery(chainInfo: ChainInfo, appId: string) {
+  const [providers, setProviders] = useState<WalletProvider[]>([]);
+  const [isDiscovering, setIsDiscovering] = useState(true);
+  const discoveryRef = useRef<DiscoverySession | null>(null);
+
+  useEffect(() => {
+    setProviders([]);
+    setIsDiscovering(true);
+
+    const discovery = WalletManager.configure({
+      extensions: { enabled: true },
+    }).getAvailableWallets({
+      chainInfo,
+      appId,
+      timeout: 60000,
+      onWalletDiscovered: (provider) => {
+        setProviders(prev => [...prev, provider]);
+      },
+    });
+
+    discoveryRef.current = discovery;
+
+    discovery.done.then(() => setIsDiscovering(false));
+
+    return () => {
+      discovery.cancel();
+      discoveryRef.current = null;
+    };
+  }, [chainInfo.chainId.toString(), chainInfo.version.toString(), appId]);
+
+  return { providers, isDiscovering, cancel: () => discoveryRef.current?.cancel() };
+}
+```
+
+## Credentialed node RPC
+
+When an embedded wallet connects to a cross-origin node that uses session cookies, opt in to browser credentials through the node client options:
+
+```typescript
+import { EmbeddedWallet } from '@aztec-labs/wallets/embedded';
+
+const wallet = await EmbeddedWallet.create('https://rpc.example.com', {
+  nodeClientOptions: {
+    fetchOptions: { credentials: 'include' },
+    maxBatchSize: 50,
+  },
+});
+```
+
+Node.js does not manage cookies automatically. Applications that need affinity there can inject any asynchronous cookie jar, including a `tough-cookie` jar installed by the application:
+
+```typescript
+import { Agent, makeUndiciFetch } from '@aztec-labs/foundation/json-rpc/undici';
+import { EmbeddedWallet } from '@aztec-labs/wallets/embedded';
+import { CookieJar } from 'tough-cookie';
+
+const wallet = await EmbeddedWallet.create('https://rpc.example.com', {
+  nodeClientOptions: {
+    fetch: makeUndiciFetch(new Agent(), new CookieJar()),
+    maxBatchSize: 50,
+  },
+});
+```
+
+Cookie storage is optional.
+
+## Storage backends
+
+Your wallet and the PXE it embeds persist state through a pluggable key-value store (`@aztec-labs/kv-store`). In the browser there are two backends:
+
+- **IndexedDB** (`@aztec-labs/kv-store/deprecated/indexeddb`): the default in browser environments up to Aztec Alpha v4, now moved to a deprecated subpath. We plan to remove this backend, so new browser code should use the SQLite backend below.
+- **SQLite-OPFS** (`@aztec-labs/kv-store/sqlite-opfs`): the default KV store backend from Aztec Alpha v5 on. It's backed by the durable Origin Private File System web standard, and it offers a number of advantages over IndexedDB: a sane transaction model (IDB transactions auto-close the moment the event loop yields, which constrains the store layer), support for encryption at rest, and better performance in the access patterns we exercise the most from both wallet and PXE.
+
+The backend is chosen by *which store you construct and hand to the wallet* there is no runtime flag or environment variable.
+
+> **Data migration is not supported between backends, by design.** The v4→v5 protocol upgrade discards all local state regardless, so switching to SQLite-OPFS simply means starting from a fresh store.
+
+### Quick start: embedded wallet with an encrypted SQLite store
+
+If you build on `@aztec-labs/wallets`' `EmbeddedWallet`, open its two stores (PXE state + the wallet DB) with `openEncryptedEmbeddedStores`, then pass them in:
+
+```typescript
+import { EmbeddedWallet } from '@aztec-labs/wallets/embedded';
+import { openEncryptedEmbeddedStores } from '@aztec-labs/wallets/embedded/store-encryption';
+import { createLogger } from '@aztec-labs/foundation/log';
+
+const log = createLogger('wallet:storage');
+
+// Your wallet derives a 32-byte key (see "Key management" below).
+// IMPORTANT: return a *fresh* Uint8Array each call. Opening a store consumes (empties)
+// the key, so a reused array would be empty on the second open (see "important" below).
+const getEncryptionKey = async () => new Uint8Array(myDerivedKey);
+
+const { pxeStore, walletStore } = await openEncryptedEmbeddedStores(
+  {
+    pxe: { name: `pxe-${rollupAddress}`, poolDirectory: '/pxe' },
+    wallet: { name: `wallet-${rollupAddress}`, poolDirectory: '/wallet' },
+  },
+  getEncryptionKey,
+  log,
+);
+
+const wallet = await EmbeddedWallet.create(nodeUrl, {
+  pxe: { store: pxeStore },
+  walletDb: { store: walletStore },
+});
+```
+
+If the supplied key cannot decrypt an existing store, `openEncryptedEmbeddedStores` throws `EmbeddedWalletEncryptionError` with `storeName: 'pxe' | 'wallet'`, which you can then surface as a "wrong password" error in your UI:
+
+```typescript
+import { EmbeddedWalletEncryptionError } from '@aztec-labs/wallets/embedded/store-encryption';
+
+try {
+  await openEncryptedEmbeddedStores(/* ... */);
+} catch (err) {
+  if (err instanceof EmbeddedWalletEncryptionError) {
+    showWrongPasswordError(); // err.storeName tells you which store failed
+  } else {
+    throw err;
+  }
+}
+```
+
+### Important 
+
+1. **Opening a store consumes the key, it does not copy it.** So that raw key material does not linger in page memory, the SDK moves your key into the storage worker and detaches the buffer on your side. The `Uint8Array` you passed comes back empty, so the same array cannot be reused to open a second store. To open more than one store with the same key, hand each open a fresh copy (`new Uint8Array(key)`). `openEncryptedEmbeddedStores` does this for you by invoking your `getEncryptionKey` callback once per store.
+2. **Each coexisting store needs its own `poolDirectory`.** The OPFS SAH Pool holds an *exclusive* lock on its directory, so two stores sharing the default pool fail with "Access Handles cannot be created if there is another open Access Handle…". Give every store a distinct, stable `poolDirectory` (stable so the same files re-open next session).
+
+### No multi-tab access: assume one tab at a time
+
+A store can be opened by **one browser tab at a time per origin**. If the user opens your wallet in a second tab of the same origin pointing at the same store, the second open contends for that lock.
+
+Thanks to the lock, the data is never corrupted, but the second open fails or hangs rather than succeeding, and there is no graceful "already open elsewhere" signal yet.
+
+Until it does, design for a single active tab: detect a second instance (e.g. with the [Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API) or a `BroadcastChannel`) and steer the user back to the existing tab, or open the store read-only there.
+
+If you need genuine concurrent multi-tab access, route all storage access through a single `SharedWorker` that you own and that holds the one connection.
+
+### Opting out of encryption
+
+If you do not need at-rest encryption (you rely on full-disk encryption, or the device is trusted), an *unencrypted* SQLite-OPFS store is still a better default than IndexedDB.
+
+The `createStore` convenience helper always uses the default OPFS pool directory and does not currently let you change it, so it only works for a single store per tab. The embedded wallet runs two stores (PXE + walletDB), so open them directly from `AztecSQLiteOPFSStore` with a distinct `poolDirectory` each:
+
+```typescript
+import { EmbeddedWallet } from '@aztec-labs/wallets/embedded';
+import { AztecSQLiteOPFSStore } from '@aztec-labs/kv-store/sqlite-opfs';
+import { createLogger } from '@aztec-labs/foundation/log';
+
+const log = createLogger('wallet:storage');
+
+// No key; just name, ephemeral=false, and a distinct poolDirectory per store.
+const pxeStore = await AztecSQLiteOPFSStore.open(log, `pxe-${rollupAddress}`, false, '/pxe');
+const walletStore = await AztecSQLiteOPFSStore.open(log, `wallet-${rollupAddress}`, false, '/wallet');
+
+const wallet = await EmbeddedWallet.create(nodeUrl, {
+  pxe: { store: pxeStore },
+  walletDb: { store: walletStore },
+});
+```
+
+### Building your own wallet (lower-level API)
+
+If you are not using `EmbeddedWallet`, construct stores directly from `@aztec-labs/kv-store/sqlite-opfs` and pass them wherever a store is accepted (e.g. `PXECreationOptions.store`):
+
+```typescript
+import { openEncryptedStore, createStore, SqliteEncryptionError } from '@aztec-labs/kv-store/sqlite-opfs';
+
+// Encrypted, persistent:
+const store = await openEncryptedStore(new Uint8Array(myDerivedKey), 'my-store', '/my-pool');
+
+// Or unencrypted:
+const plain = await createStore('my-store', { dataStoreMapSizeKb: 2e10 });
+```
+
+Note: `dataStoreMapSizeKb` is an LMDB-specific ceiling (the maximum memory-map size). SQLite-OPFS grows its file dynamically and ignores the value, but it is a required field of the shared `DataStoreConfig` type, so you must still pass something (any number is fine). We will fix this implementation leak in coming versions.
+
+Note: `openEncryptedStore` throws `SqliteEncryptionError` (with a typed `code`, e.g. `'decrypt_failed'`) on a bad key.
+
+### Using SQLite-OPFS in a browser extension (MV3)
+
+SQLite-OPFS needs OPFS, a Web Worker, and cross-origin isolation (SharedArrayBuffer). In a Chrome MV3 extension:
+
+- **Run it in an offscreen document, not the background service worker.** The service worker is ephemeral and does not reliably provide OPFS/SharedArrayBuffer; an offscreen document does, and it is where your PXE and stores should live.
+- **No COOP/COEP header setup is needed inside the extension.** Extension pages are cross-origin-isolated by default. (A plain web page hosting the wallet *does* need those headers.)
+
+### Key management is your responsibility
+
+The store encrypts data at rest given a 32-byte key, but deriving and safeguarding that key is the wallet's job. A common pattern is to derive the key from a user password with a memory-hard KDF (e.g. Argon2id) and hold it only in memory while the wallet is unlocked. Adapt this to your own security model.

package/dest/base-wallet/base_wallet.d.ts

@@ -0,0 +1,179 @@
+import type { Account, NoFrom } from '@aztec-labs/aztec.js/account';
+import type { CallIntent, IntentInnerHash } from '@aztec-labs/aztec.js/authorization';
+import { type InteractionWaitOptions, type SendReturn } from '@aztec-labs/aztec.js/contracts';
+import type { FeePaymentMethod } from '@aztec-labs/aztec.js/fee';
+import { type Aliased, type AppCapabilities, type BatchResults, type BatchedMethod, ContractInitializationStatus, type ExecuteUtilityOptions, type PrivateEvent, type PrivateEventFilter, type ProfileOptions, type SendOptions, type SimulateOptions, TxSimulationResultWithAppOffset, type Wallet, type WalletCapabilities } from '@aztec-labs/aztec.js/wallet';
+import { AccountFeePaymentMethodOptions } from '@aztec-labs/entrypoints/account';
+import type { ChainInfo } from '@aztec-labs/entrypoints/interfaces';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+import type { PXE } from '@aztec-labs/pxe/server';
+import { type ContractArtifact, type EventMetadataDefinition, type FunctionCall } from '@aztec-labs/stdlib/abi';
+import type { AuthWitness } from '@aztec-labs/stdlib/auth-witness';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { type ContractInstancePreimage } from '@aztec-labs/stdlib/contract';
+import { Gas, GasFees, GasSettings, ManaUsageEstimate } from '@aztec-labs/stdlib/gas';
+import type { AztecNode } from '@aztec-labs/stdlib/interfaces/client';
+import { type MasterSecretKeys } from '@aztec-labs/stdlib/keys';
+import { ExecutionPayload, type TxExecutionRequest, type TxProfileResult, type UtilityExecutionResult } from '@aztec-labs/stdlib/tx';
+/**
+ * Options to configure fee payment for a transaction
+ */
+export type FeeOptions = {
+    /**
+     * A wallet-provided fallback fee payment method that is used only if the transaction that is being constructed
+     * doesn't already include one
+     */
+    walletFeePaymentMethod?: FeePaymentMethod;
+    /** Configuration options for the account to properly handle the selected fee payment method */
+    accountFeePaymentMethodOptions?: AccountFeePaymentMethodOptions;
+    /** The gas settings to use for the transaction */
+    gasSettings: GasSettings;
+};
+/** Options for `simulateViaEntrypoint`. */
+export type SimulateViaEntrypointOptions = Pick<SimulateOptions, 'from' | 'additionalScopes' | 'skipTxValidation' | 'skipFeeEnforcement' | 'sendMessagesAs' | 'overrides'> & {
+    /** Fee options for the entrypoint */
+    feeOptions: FeeOptions;
+};
+/** Options for `completeFeeOptions`. */
+export type CompleteFeeOptionsConfig = {
+    /** The address where the transaction is being sent from. */
+    from: AztecAddress | NoFrom;
+    /** The address paying for fees (if any fee payment method is embedded in the execution payload). */
+    feePayer?: AztecAddress;
+    /** User-provided partial gas settings. */
+    gasSettings?: Partial<FieldsOf<GasSettings>>;
+    /** If true, returns gas settings with high gas limits for estimation. If false, uses fallback limits. */
+    forEstimation?: boolean;
+    /**
+     * Assumed network congestion level for fee prediction. Controls how aggressively the wallet
+     * estimates future fees. Defaults to Limit (worst case) when not specified.
+     */
+    congestionEstimate?: ManaUsageEstimate;
+};
+/**
+ * A base class for Wallet implementations
+ */
+export declare abstract class BaseWallet implements Wallet {
+    protected readonly pxe: PXE;
+    protected readonly aztecNode: AztecNode;
+    protected log: import("@aztec-labs/foundation/log").Logger;
+    protected minFeePadding: number;
+    protected cancellableTransactions: boolean;
+    protected defaultWaitInterval?: number;
+    private nodeInfoPromise;
+    protected constructor(pxe: PXE, aztecNode: AztecNode, log?: import("@aztec-labs/foundation/log").Logger);
+    protected scopesFrom(from: AztecAddress | NoFrom, additionalScopes: AztecAddress[], sendMessagesAs: AztecAddress | undefined): AztecAddress[];
+    /**
+     * Picks the sender address PXE should tag private messages with. Returns `undefined` when there is no signing
+     * account (`from === NO_FROM`) and no explicit override; in that case any private log emitted by the tx using
+     * the wallet-supplied default sender will fail the "Sender for tags is not set" assertion.
+     * @param from - Tx sender, or `NO_FROM`.
+     * @param sendMessagesAs - Explicit override.
+     */
+    protected senderForTagsFrom(from: AztecAddress | NoFrom, sendMessagesAs?: AztecAddress): AztecAddress | undefined;
+    protected abstract getAccountFromAddress(address: AztecAddress): Promise<Account>;
+    abstract getAccounts(): Promise<Aliased<AztecAddress>[]>;
+    /**
+     * Returns the list of aliased contacts associated with the wallet.
+     * This base implementation directly returns PXE's senders, but note that in general contacts are a superset of senders.
+     *  - Senders: Addresses we check during synching in case they sent us notes,
+     *  - Contacts: more general concept akin to a phone's contact list.
+     * @returns The aliased collection of AztecAddresses that form this wallet's address book
+     */
+    getAddressBook(): Promise<Aliased<AztecAddress>[]>;
+    /**
+     * Fetches and caches the node info for the wallet's lifetime, since a wallet talks to a single network and
+     * node info never changes. A rejected fetch clears the cache so the next call retries instead of replaying
+     * the cached rejection forever — important because the gas-limit fill-in and validation (run on every send)
+     * depend on it.
+     */
+    private getNodeInfo;
+    getChainInfo(): Promise<ChainInfo>;
+    /**
+     * Returns the maximum gas limits a single transaction may declare on this wallet's network (the
+     * node-advertised `txsLimits.gas`). Internal helper used to fill in default gas limits when sending a
+     * transaction without explicit limits, and to validate caller-provided limits before sending. Backed by
+     * the cached node info, since a wallet talks to a single network.
+     */
+    protected getMaxTxGasLimits(): Promise<Gas>;
+    protected createTxExecutionRequestFromPayloadAndFee(executionPayload: ExecutionPayload, from: AztecAddress | NoFrom, feeOptions: FeeOptions): Promise<TxExecutionRequest>;
+    createAuthWit(from: AztecAddress, messageHashOrIntent: IntentInnerHash | CallIntent): Promise<AuthWitness>;
+    /**
+     * Request capabilities from the wallet.
+     *
+     * This method is wallet-implementation-dependent and must be provided by classes extending BaseWallet.
+     * Embedded wallets typically don't support capability-based authorization (no user authorization flow),
+     * while external wallets (browser extensions, hardware wallets) implement this to reduce authorization
+     * friction by allowing apps to request permissions upfront.
+     *
+     * TODO: Consider making it abstract so implementing it is a conscious decision. Leaving it as-is
+     * while the feature stabilizes.
+     *
+     * @param _manifest - Application capability manifest declaring what operations the app needs
+     */
+    requestCapabilities(_manifest: AppCapabilities): Promise<WalletCapabilities>;
+    batch<const T extends readonly BatchedMethod[]>(methods: T): Promise<BatchResults<T>>;
+    /**
+     * Completes partial user-provided fee options with wallet defaults.
+     * @param config - Fee completion config.
+     */
+    protected completeFeeOptions(config: CompleteFeeOptionsConfig): Promise<FeeOptions>;
+    /**
+     * Returns the worst-case min fee across predicted future slots.
+     * Falls back to getCurrentMinFees if the node doesn't support getPredictedMinFees.
+     * @param estimate - The mana usage estimate to use for fee prediction. Defaults to Limit for conservative estimation.
+     */
+    protected getMinFees(estimate?: ManaUsageEstimate): Promise<GasFees>;
+    registerSender(address: AztecAddress, _alias?: string): Promise<AztecAddress>;
+    registerContract(instance: ContractInstancePreimage, artifact?: ContractArtifact, secretKeyOrKeys?: Fr | MasterSecretKeys): Promise<void>;
+    registerContractClass(artifact: ContractArtifact): Promise<void>;
+    /**
+     * Simulates calls through the standard PXE path (account entrypoint).
+     * @param executionPayload - The execution payload to simulate.
+     * @param opts - Simulation options.
+     */
+    protected simulateViaEntrypoint(executionPayload: ExecutionPayload, opts: SimulateViaEntrypointOptions): Promise<TxSimulationResultWithAppOffset>;
+    /**
+     * Computes the index where the app's calls begin in the flattened array of calls (0 = entrypoint/root, 1..N = fee
+     * calls, N+1 = app).
+     * @param from - The sender address, or NO_FROM for the default entrypoint.
+     * @param feeOptions - Fee options containing the wallet fee payment method.
+     */
+    protected computeAppCallOffset(from: AztecAddress | NoFrom, feeOptions: FeeOptions): Promise<number>;
+    /**
+     * Simulates a transaction, optimizing leading public static calls by running them directly
+     * on the node while sending the remaining calls through the standard PXE path.
+     * Return values from both paths are merged back in original call order.
+     * @param executionPayload - The execution payload to simulate.
+     * @param opts - Simulation options (from address, fee settings, etc.).
+     * @returns The merged simulation result.
+     */
+    simulateTx(executionPayload: ExecutionPayload, opts: SimulateOptions): Promise<TxSimulationResultWithAppOffset>;
+    profileTx(executionPayload: ExecutionPayload, opts: ProfileOptions): Promise<TxProfileResult>;
+    sendTx<W extends InteractionWaitOptions = undefined>(executionPayload: ExecutionPayload, opts: SendOptions<W>): Promise<SendReturn<W>>;
+    /**
+     * Resolves a contract address to a human-readable name via PXE, if available.
+     * @param address - The contract address to resolve.
+     */
+    protected getContractName(address: AztecAddress): Promise<string | undefined>;
+    protected contextualizeError(err: Error, ...context: string[]): Error;
+    executeUtility(call: FunctionCall, opts: ExecuteUtilityOptions): Promise<UtilityExecutionResult>;
+    getPrivateEvents<T>(eventDef: EventMetadataDefinition, eventFilter: PrivateEventFilter): Promise<PrivateEvent<T>[]>;
+    /**
+     * Returns metadata about a contract, including whether it has been initialized, published, and updated.
+     * @param address - The contract address to query.
+     */
+    getContractMetadata(address: AztecAddress): Promise<{
+        instance: import("@aztec-labs/stdlib/contract").ContractInstancePreimageWithAddress | undefined;
+        initializationStatus: ContractInitializationStatus;
+        isContractPublished: boolean;
+        isContractUpdated: boolean;
+        updatedContractClassId: Fr | undefined;
+    }>;
+    getContractClassMetadata(id: Fr): Promise<{
+        isArtifactRegistered: boolean;
+        isContractClassPubliclyRegistered: boolean;
+    }>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFzZV93YWxsZXQuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9iYXNlLXdhbGxldC9iYXNlX3dhbGxldC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxPQUFPLEVBQUUsTUFBTSxFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFFcEUsT0FBTyxLQUFLLEVBQUUsVUFBVSxFQUFFLGVBQWUsRUFBRSxNQUFNLG9DQUFvQyxDQUFDO0FBQ3RGLE9BQU8sRUFFTCxLQUFLLHNCQUFzQixFQUUzQixLQUFLLFVBQVUsRUFHaEIsTUFBTSxnQ0FBZ0MsQ0FBQztBQUN4QyxPQUFPLEtBQUssRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBRWpFLE9BQU8sRUFDTCxLQUFLLE9BQU8sRUFDWixLQUFLLGVBQWUsRUFDcEIsS0FBSyxZQUFZLEVBQ2pCLEtBQUssYUFBYSxFQUNsQiw0QkFBNEIsRUFDNUIsS0FBSyxxQkFBcUIsRUFDMUIsS0FBSyxZQUFZLEVBQ2pCLEtBQUssa0JBQWtCLEVBQ3ZCLEtBQUssY0FBYyxFQUNuQixLQUFLLFdBQVcsRUFDaEIsS0FBSyxlQUFlLEVBQ3BCLCtCQUErQixFQUMvQixLQUFLLE1BQU0sRUFDWCxLQUFLLGtCQUFrQixFQUN4QixNQUFNLDZCQUE2QixDQUFDO0FBQ3JDLE9BQU8sRUFBRSw4QkFBOEIsRUFBd0MsTUFBTSxpQ0FBaUMsQ0FBQztBQUV2SCxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSxvQ0FBb0MsQ0FBQztBQUNwRSxPQUFPLEVBQUUsRUFBRSxFQUFFLE1BQU0scUNBQXFDLENBQUM7QUFFekQsT0FBTyxLQUFLLEVBQUUsUUFBUSxFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFFN0QsT0FBTyxLQUFLLEVBQUUsR0FBRyxFQUFzQixNQUFNLHdCQUF3QixDQUFDO0FBQ3RFLE9BQU8sRUFDTCxLQUFLLGdCQUFnQixFQUNyQixLQUFLLHVCQUF1QixFQUM1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