@awarizon/web3 1.1.0 → 1.2.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { Chain, WalletClient, Address, Abi, PublicClient, Hex } from 'viem';
 export { Abi, Address, Chain, Hash, TransactionReceipt, WalletClient } from 'viem';
-import { WalletEngine, CreatedWallet, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, ExternalWalletClient } from '@awarizon/wallet-engine';
-export { ChainSwitchError, InvalidMnemonicError, InvalidPrivateKeyError, WalletEngine, WalletNotConnectedError } from '@awarizon/wallet-engine';
+import { WalletEngine, CreatedWallet, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, ConnectorInfo, ExternalWalletClient, EIP1193Provider, SignTypedDataParams, WalletChangeEvent, ChainChangeEvent } from '@awarizon/wallet-engine';
+export { ChainChangeEvent, ChainMismatchError, ChainSwitchError, ConnectorInfo, CreatedWallet, EIP1193Provider, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, InvalidMnemonicError, InvalidPrivateKeyError, SignTypedDataParams, WalletChangeEvent, WalletEngine, WalletNotConnectedError } from '@awarizon/wallet-engine';
 import { TransactionResult } from '@awarizon/tx-engine';
 export { ContractExecutionError, GasEstimationError, SimulationError, TransactionEngine, TransactionResult, TransactionTimeoutError } from '@awarizon/tx-engine';
 export { DuplicateFunctionError, InvalidABIError, UnsupportedABIItemError, generateAllMethodSignatures, generateMethodSignature, isPayableFunction, isWriteFunction, parseABI } from '@awarizon/abi-engine';
@@ -34,6 +34,23 @@ interface AwarizonConfig {
      * Override for local development or staging environments.
      */
     baseUrl?: string;
+    /**
+     * When true, the SDK automatically requests a chain switch on the external
+     * wallet before every write if the wallet is on the wrong network.
+     * Only affects external wallets (wagmi, RainbowKit, EIP-1193).
+     */
+    autoSwitchChain?: boolean;
+    /**
+     * WalletConnect v2 project ID.
+     * Required when using `awarizon.connectWalletConnect()` or the built-in
+     * `<ConnectButton />` to connect mobile wallets via WalletConnect.
+     *
+     * Get a free project ID at https://cloud.walletconnect.com
+     *
+     * @example
+     * new AwarizonWeb3({ chain: "base", apiKey: "awz_live_...", walletConnectProjectId: "abc123" })
+     */
+    walletConnectProjectId?: string;
 }
 interface ContractConfig<TAbi extends Abi = Abi> {
     /** The deployed contract address */
@@ -76,6 +93,8 @@ interface SDKWalletInfo {
     address: Address;
     chain: Chain;
     isExternal: boolean;
+    /** Name of the connector if an external wallet is active, e.g. "MetaMask" */
+    connectorName?: string;
 }
 interface ContractRegistryEntry {
     address: Address;
@@ -661,10 +680,26 @@ declare class WalletProxy {
     isConnected(): boolean;
     hasExternalWallet(): boolean;
     hasInternalWallet(): boolean;
-    connectExternal(c: ExternalWalletClient): void;
+    getConnectorInfo(): ConnectorInfo;
+    connectExternal(c: ExternalWalletClient, info?: {
+        name?: string;
+        icon?: string;
+    }): void;
     disconnectExternal(): void;
     disconnect(): void;
     switchChain(chain: Chain): Promise<void>;
+    connectEIP1193(provider: EIP1193Provider, info?: {
+        name?: string;
+        icon?: string;
+    }): Promise<void>;
+    signMessage(message: string | {
+        raw: Hex | Uint8Array;
+    }): Promise<Hex>;
+    signTypedData(params: SignTypedDataParams): Promise<Hex>;
+    getChainId(): Promise<number>;
+    isChainMismatch(): Promise<boolean>;
+    onWalletChange(cb: (event: WalletChangeEvent) => void): () => void;
+    onChainChange(cb: (event: ChainChangeEvent) => void): () => void;
 }
 /**
  * Primary entry point for the Awarizon Web3 SDK.
@@ -691,13 +726,110 @@ declare class AwarizonWeb3 {
     private readonly _engine;
     private readonly _txEngine;
     private readonly _telemetry;
+    private readonly _walletConnectProjectId;
     private _contractCache;
     private _registry;
     constructor(config: AwarizonConfig);
-    connectWallet(walletClient: WalletClient): this;
+    /**
+     * Connect any viem WalletClient (wagmi, RainbowKit, custom).
+     * Optionally pass connector metadata to display in the UI.
+     *
+     * @example
+     * awarizon.connectWallet(walletClient, { name: "MetaMask" })
+     */
+    connectWallet(walletClient: WalletClient, connectorInfo?: {
+        name?: string;
+        icon?: string;
+    }): this;
+    /**
+     * Connect directly from a raw EIP-1193 provider without needing wagmi.
+     * Works with window.ethereum, WalletConnect v2, and any EIP-1193 object.
+     *
+     * @example
+     * await awarizon.connectEIP1193Provider(window.ethereum, { name: "MetaMask" })
+     */
+    connectEIP1193Provider(provider: EIP1193Provider, connectorInfo?: {
+        name?: string;
+        icon?: string;
+    }): Promise<this>;
+    /**
+     * Connect a mobile or desktop wallet using the WalletConnect v2 protocol.
+     * Opens a QR-code modal (or deeplink on mobile) so the user can scan with
+     * MetaMask, Rainbow, Trust Wallet, or any WalletConnect-compatible wallet.
+     *
+     * Requires `walletConnectProjectId` in the SDK config and the peer package:
+     * `npm install @walletconnect/ethereum-provider`
+     *
+     * @example
+     * ```ts
+     * const awarizon = new AwarizonWeb3({ chain: "base", apiKey: "...", walletConnectProjectId: "abc" })
+     * await awarizon.connectWalletConnect()
+     * ```
+     */
+    connectWalletConnect(): Promise<this>;
+    /** The WalletConnect project ID passed at construction, if any */
+    get walletConnectProjectId(): string | undefined;
     disconnectWallet(): this;
     switchChain(chain: Chain | string): Promise<this>;
     getWalletInfo(): SDKWalletInfo;
+    /**
+     * Sign a plain text or raw-bytes message.
+     * Use for Sign-In with Ethereum (SIWE) and off-chain authorization.
+     *
+     * @example
+     * const sig = await awarizon.signMessage("Hello, Awarizon!")
+     */
+    signMessage(message: string | {
+        raw: Hex | Uint8Array;
+    }): Promise<Hex>;
+    /**
+     * Sign EIP-712 typed structured data (permit2, SIWE, Seaport orders, etc.).
+     *
+     * @example
+     * const sig = await awarizon.signTypedData({
+     *   domain: { name: "MyApp", version: "1", chainId: 8453 },
+     *   types:  { Transfer: [{ name: "to", type: "address" }, { name: "amount", type: "uint256" }] },
+     *   primaryType: "Transfer",
+     *   message: { to: "0x...", amount: "1000000" },
+     * })
+     */
+    signTypedData(params: SignTypedDataParams): Promise<Hex>;
+    /**
+     * Returns the chain ID the active wallet is currently on.
+     * For external wallets this may differ from the SDK's configured chain.
+     */
+    getChainId(): Promise<number>;
+    /**
+     * Returns true when the external wallet is on a different chain than the SDK.
+     * Use this to show a "wrong network" banner in your UI.
+     *
+     * @example
+     * if (await awarizon.isChainMismatch()) {
+     *   alert("Please switch to Base in your wallet")
+     * }
+     */
+    isChainMismatch(): Promise<boolean>;
+    /**
+     * Returns metadata about the currently active connector.
+     * Useful for displaying "Connected via MetaMask" in the UI.
+     */
+    getConnectorInfo(): ConnectorInfo;
+    /**
+     * Subscribe to wallet changes (connect, disconnect, account switch).
+     * Returns an unsubscribe function — call it on cleanup.
+     *
+     * @example
+     * const unsub = awarizon.onWalletChange(({ address, type, name }) => {
+     *   console.log("Wallet changed:", address, type, name)
+     * })
+     * unsub() // stop listening
+     */
+    onWalletChange(cb: (event: WalletChangeEvent) => void): () => void;
+    /**
+     * Subscribe to chain changes (switchChain calls).
+     * Returns an unsubscribe function.
+     */
+    onChainChange(cb: (event: ChainChangeEvent) => void): () => void;
     /**
      * Load a deployed contract and return a fully typed, ABI-powered instance.
      * Validates the API key on the first call — subsequent calls are instant.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Chain, WalletClient, Address, Abi, PublicClient, Hex } from 'viem';
 export { Abi, Address, Chain, Hash, TransactionReceipt, WalletClient } from 'viem';
-import { WalletEngine, CreatedWallet, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, ExternalWalletClient } from '@awarizon/wallet-engine';
-export { ChainSwitchError, InvalidMnemonicError, InvalidPrivateKeyError, WalletEngine, WalletNotConnectedError } from '@awarizon/wallet-engine';
+import { WalletEngine, CreatedWallet, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, ConnectorInfo, ExternalWalletClient, EIP1193Provider, SignTypedDataParams, WalletChangeEvent, ChainChangeEvent } from '@awarizon/wallet-engine';
+export { ChainChangeEvent, ChainMismatchError, ChainSwitchError, ConnectorInfo, CreatedWallet, EIP1193Provider, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, InvalidMnemonicError, InvalidPrivateKeyError, SignTypedDataParams, WalletChangeEvent, WalletEngine, WalletNotConnectedError } from '@awarizon/wallet-engine';
 import { TransactionResult } from '@awarizon/tx-engine';
 export { ContractExecutionError, GasEstimationError, SimulationError, TransactionEngine, TransactionResult, TransactionTimeoutError } from '@awarizon/tx-engine';
 export { DuplicateFunctionError, InvalidABIError, UnsupportedABIItemError, generateAllMethodSignatures, generateMethodSignature, isPayableFunction, isWriteFunction, parseABI } from '@awarizon/abi-engine';
@@ -34,6 +34,23 @@ interface AwarizonConfig {
      * Override for local development or staging environments.
      */
     baseUrl?: string;
+    /**
+     * When true, the SDK automatically requests a chain switch on the external
+     * wallet before every write if the wallet is on the wrong network.
+     * Only affects external wallets (wagmi, RainbowKit, EIP-1193).
+     */
+    autoSwitchChain?: boolean;
+    /**
+     * WalletConnect v2 project ID.
+     * Required when using `awarizon.connectWalletConnect()` or the built-in
+     * `<ConnectButton />` to connect mobile wallets via WalletConnect.
+     *
+     * Get a free project ID at https://cloud.walletconnect.com
+     *
+     * @example
+     * new AwarizonWeb3({ chain: "base", apiKey: "awz_live_...", walletConnectProjectId: "abc123" })
+     */
+    walletConnectProjectId?: string;
 }
 interface ContractConfig<TAbi extends Abi = Abi> {
     /** The deployed contract address */
@@ -76,6 +93,8 @@ interface SDKWalletInfo {
     address: Address;
     chain: Chain;
     isExternal: boolean;
+    /** Name of the connector if an external wallet is active, e.g. "MetaMask" */
+    connectorName?: string;
 }
 interface ContractRegistryEntry {
     address: Address;
@@ -661,10 +680,26 @@ declare class WalletProxy {
     isConnected(): boolean;
     hasExternalWallet(): boolean;
     hasInternalWallet(): boolean;
-    connectExternal(c: ExternalWalletClient): void;
+    getConnectorInfo(): ConnectorInfo;
+    connectExternal(c: ExternalWalletClient, info?: {
+        name?: string;
+        icon?: string;
+    }): void;
     disconnectExternal(): void;
     disconnect(): void;
     switchChain(chain: Chain): Promise<void>;
+    connectEIP1193(provider: EIP1193Provider, info?: {
+        name?: string;
+        icon?: string;
+    }): Promise<void>;
+    signMessage(message: string | {
+        raw: Hex | Uint8Array;
+    }): Promise<Hex>;
+    signTypedData(params: SignTypedDataParams): Promise<Hex>;
+    getChainId(): Promise<number>;
+    isChainMismatch(): Promise<boolean>;
+    onWalletChange(cb: (event: WalletChangeEvent) => void): () => void;
+    onChainChange(cb: (event: ChainChangeEvent) => void): () => void;
 }
 /**
  * Primary entry point for the Awarizon Web3 SDK.
@@ -691,13 +726,110 @@ declare class AwarizonWeb3 {
     private readonly _engine;
     private readonly _txEngine;
     private readonly _telemetry;
+    private readonly _walletConnectProjectId;
     private _contractCache;
     private _registry;
     constructor(config: AwarizonConfig);
-    connectWallet(walletClient: WalletClient): this;
+    /**
+     * Connect any viem WalletClient (wagmi, RainbowKit, custom).
+     * Optionally pass connector metadata to display in the UI.
+     *
+     * @example
+     * awarizon.connectWallet(walletClient, { name: "MetaMask" })
+     */
+    connectWallet(walletClient: WalletClient, connectorInfo?: {
+        name?: string;
+        icon?: string;
+    }): this;
+    /**
+     * Connect directly from a raw EIP-1193 provider without needing wagmi.
+     * Works with window.ethereum, WalletConnect v2, and any EIP-1193 object.
+     *
+     * @example
+     * await awarizon.connectEIP1193Provider(window.ethereum, { name: "MetaMask" })
+     */
+    connectEIP1193Provider(provider: EIP1193Provider, connectorInfo?: {
+        name?: string;
+        icon?: string;
+    }): Promise<this>;
+    /**
+     * Connect a mobile or desktop wallet using the WalletConnect v2 protocol.
+     * Opens a QR-code modal (or deeplink on mobile) so the user can scan with
+     * MetaMask, Rainbow, Trust Wallet, or any WalletConnect-compatible wallet.
+     *
+     * Requires `walletConnectProjectId` in the SDK config and the peer package:
+     * `npm install @walletconnect/ethereum-provider`
+     *
+     * @example
+     * ```ts
+     * const awarizon = new AwarizonWeb3({ chain: "base", apiKey: "...", walletConnectProjectId: "abc" })
+     * await awarizon.connectWalletConnect()
+     * ```
+     */
+    connectWalletConnect(): Promise<this>;
+    /** The WalletConnect project ID passed at construction, if any */
+    get walletConnectProjectId(): string | undefined;
     disconnectWallet(): this;
     switchChain(chain: Chain | string): Promise<this>;
     getWalletInfo(): SDKWalletInfo;
+    /**
+     * Sign a plain text or raw-bytes message.
+     * Use for Sign-In with Ethereum (SIWE) and off-chain authorization.
+     *
+     * @example
+     * const sig = await awarizon.signMessage("Hello, Awarizon!")
+     */
+    signMessage(message: string | {
+        raw: Hex | Uint8Array;
+    }): Promise<Hex>;
+    /**
+     * Sign EIP-712 typed structured data (permit2, SIWE, Seaport orders, etc.).
+     *
+     * @example
+     * const sig = await awarizon.signTypedData({
+     *   domain: { name: "MyApp", version: "1", chainId: 8453 },
+     *   types:  { Transfer: [{ name: "to", type: "address" }, { name: "amount", type: "uint256" }] },
+     *   primaryType: "Transfer",
+     *   message: { to: "0x...", amount: "1000000" },
+     * })
+     */
+    signTypedData(params: SignTypedDataParams): Promise<Hex>;
+    /**
+     * Returns the chain ID the active wallet is currently on.
+     * For external wallets this may differ from the SDK's configured chain.
+     */
+    getChainId(): Promise<number>;
+    /**
+     * Returns true when the external wallet is on a different chain than the SDK.
+     * Use this to show a "wrong network" banner in your UI.
+     *
+     * @example
+     * if (await awarizon.isChainMismatch()) {
+     *   alert("Please switch to Base in your wallet")
+     * }
+     */
+    isChainMismatch(): Promise<boolean>;
+    /**
+     * Returns metadata about the currently active connector.
+     * Useful for displaying "Connected via MetaMask" in the UI.
+     */
+    getConnectorInfo(): ConnectorInfo;
+    /**
+     * Subscribe to wallet changes (connect, disconnect, account switch).
+     * Returns an unsubscribe function — call it on cleanup.
+     *
+     * @example
+     * const unsub = awarizon.onWalletChange(({ address, type, name }) => {
+     *   console.log("Wallet changed:", address, type, name)
+     * })
+     * unsub() // stop listening
+     */
+    onWalletChange(cb: (event: WalletChangeEvent) => void): () => void;
+    /**
+     * Subscribe to chain changes (switchChain calls).
+     * Returns an unsubscribe function.
+     */
+    onChainChange(cb: (event: ChainChangeEvent) => void): () => void;
     /**
      * Load a deployed contract and return a fully typed, ABI-powered instance.
      * Validates the API key on the first call — subsequent calls are instant.

package/dist/index.js

@@ -428,8 +428,11 @@ var WalletProxy = class {
   hasInternalWallet() {
     return this.engine.hasInternalWallet();
   }
-  connectExternal(c) {
-    this.engine.connectExternal(c);
+  getConnectorInfo() {
+    return this.engine.getConnectorInfo();
+  }
+  connectExternal(c, info) {
+    this.engine.connectExternal(c, info);
   }
   disconnectExternal() {
     this.engine.disconnectExternal();
@@ -440,6 +443,32 @@ var WalletProxy = class {
   async switchChain(chain) {
     return this.engine.switchChain(chain);
   }
+  // ── Gated async — EIP-1193, signing, chain awareness ───────────────────────
+  async connectEIP1193(provider, info) {
+    await this.ensureReady();
+    return this.engine.connectEIP1193(provider, info);
+  }
+  async signMessage(message) {
+    await this.ensureReady();
+    return this.engine.signMessage(message);
+  }
+  async signTypedData(params) {
+    await this.ensureReady();
+    return this.engine.signTypedData(params);
+  }
+  async getChainId() {
+    return this.engine.getChainId();
+  }
+  async isChainMismatch() {
+    return this.engine.isChainMismatch();
+  }
+  // ── Event subscriptions ────────────────────────────────────────────────────
+  onWalletChange(cb) {
+    return this.engine.onWalletChange(cb);
+  }
+  onChainChange(cb) {
+    return this.engine.onChainChange(cb);
+  }
 };
 var AwarizonWeb3 = class {
   constructor(config) {
@@ -464,6 +493,7 @@ var AwarizonWeb3 = class {
       () => this._engine.getWalletClient()
     );
     this._telemetry = new TelemetryClient(config.apiKey, config.baseUrl);
+    this._walletConnectProjectId = config.walletConnectProjectId;
     this.wallet = new WalletProxy(
       this._engine,
       () => this._telemetry.ensureValidated()
@@ -473,10 +503,77 @@ var AwarizonWeb3 = class {
     }
   }
   // ─── Wallet API surface ─────────────────────────────────────────────────────
-  connectWallet(walletClient) {
-    this._engine.connectExternal(walletClient);
+  /**
+   * Connect any viem WalletClient (wagmi, RainbowKit, custom).
+   * Optionally pass connector metadata to display in the UI.
+   *
+   * @example
+   * awarizon.connectWallet(walletClient, { name: "MetaMask" })
+   */
+  connectWallet(walletClient, connectorInfo) {
+    this._engine.connectExternal(walletClient, connectorInfo);
     return this;
   }
+  /**
+   * Connect directly from a raw EIP-1193 provider without needing wagmi.
+   * Works with window.ethereum, WalletConnect v2, and any EIP-1193 object.
+   *
+   * @example
+   * await awarizon.connectEIP1193Provider(window.ethereum, { name: "MetaMask" })
+   */
+  async connectEIP1193Provider(provider, connectorInfo) {
+    await this._telemetry.ensureValidated();
+    await this._engine.connectEIP1193(provider, connectorInfo);
+    return this;
+  }
+  /**
+   * Connect a mobile or desktop wallet using the WalletConnect v2 protocol.
+   * Opens a QR-code modal (or deeplink on mobile) so the user can scan with
+   * MetaMask, Rainbow, Trust Wallet, or any WalletConnect-compatible wallet.
+   *
+   * Requires `walletConnectProjectId` in the SDK config and the peer package:
+   * `npm install @walletconnect/ethereum-provider`
+   *
+   * @example
+   * ```ts
+   * const awarizon = new AwarizonWeb3({ chain: "base", apiKey: "...", walletConnectProjectId: "abc" })
+   * await awarizon.connectWalletConnect()
+   * ```
+   */
+  async connectWalletConnect() {
+    if (!this._walletConnectProjectId) {
+      throw new Error(
+        '[awarizon/web3] walletConnectProjectId is not configured. Pass it when creating the SDK: new AwarizonWeb3({ ..., walletConnectProjectId: "your_id" }).\nGet a free project ID at https://cloud.walletconnect.com'
+      );
+    }
+    let EthereumProvider;
+    try {
+      const load = new Function("id", "return import(id)");
+      EthereumProvider = (await load("@walletconnect/ethereum-provider")).default;
+    } catch {
+      throw new Error(
+        "[awarizon/web3] @walletconnect/ethereum-provider is not installed.\nRun: npm install @walletconnect/ethereum-provider"
+      );
+    }
+    const provider = await EthereumProvider.init({
+      projectId: this._walletConnectProjectId,
+      chains: [this.chain.id],
+      showQrModal: true,
+      optionalChains: [],
+      methods: ["eth_sendTransaction", "personal_sign", "eth_signTypedData_v4"],
+      events: ["chainChanged", "accountsChanged"]
+    });
+    await provider.connect();
+    await this.connectEIP1193Provider(provider, {
+      name: "WalletConnect",
+      icon: "https://avatars.githubusercontent.com/u/37784886"
+    });
+    return this;
+  }
+  /** The WalletConnect project ID passed at construction, if any */
+  get walletConnectProjectId() {
+    return this._walletConnectProjectId;
+  }
   disconnectWallet() {
     this._engine.disconnectExternal();
     return this;
@@ -489,12 +586,86 @@ var AwarizonWeb3 = class {
     return this;
   }
   getWalletInfo() {
+    const info = this._engine.getConnectorInfo();
     return {
       address: this._engine.address(),
       chain: this.chain,
-      isExternal: this._engine.hasExternalWallet()
+      isExternal: this._engine.hasExternalWallet(),
+      connectorName: info.name
     };
   }
+  /**
+   * Sign a plain text or raw-bytes message.
+   * Use for Sign-In with Ethereum (SIWE) and off-chain authorization.
+   *
+   * @example
+   * const sig = await awarizon.signMessage("Hello, Awarizon!")
+   */
+  async signMessage(message) {
+    await this._telemetry.ensureValidated();
+    return this._engine.signMessage(message);
+  }
+  /**
+   * Sign EIP-712 typed structured data (permit2, SIWE, Seaport orders, etc.).
+   *
+   * @example
+   * const sig = await awarizon.signTypedData({
+   *   domain: { name: "MyApp", version: "1", chainId: 8453 },
+   *   types:  { Transfer: [{ name: "to", type: "address" }, { name: "amount", type: "uint256" }] },
+   *   primaryType: "Transfer",
+   *   message: { to: "0x...", amount: "1000000" },
+   * })
+   */
+  async signTypedData(params) {
+    await this._telemetry.ensureValidated();
+    return this._engine.signTypedData(params);
+  }
+  /**
+   * Returns the chain ID the active wallet is currently on.
+   * For external wallets this may differ from the SDK's configured chain.
+   */
+  async getChainId() {
+    return this._engine.getChainId();
+  }
+  /**
+   * Returns true when the external wallet is on a different chain than the SDK.
+   * Use this to show a "wrong network" banner in your UI.
+   *
+   * @example
+   * if (await awarizon.isChainMismatch()) {
+   *   alert("Please switch to Base in your wallet")
+   * }
+   */
+  async isChainMismatch() {
+    return this._engine.isChainMismatch();
+  }
+  /**
+   * Returns metadata about the currently active connector.
+   * Useful for displaying "Connected via MetaMask" in the UI.
+   */
+  getConnectorInfo() {
+    return this._engine.getConnectorInfo();
+  }
+  /**
+   * Subscribe to wallet changes (connect, disconnect, account switch).
+   * Returns an unsubscribe function — call it on cleanup.
+   *
+   * @example
+   * const unsub = awarizon.onWalletChange(({ address, type, name }) => {
+   *   console.log("Wallet changed:", address, type, name)
+   * })
+   * unsub() // stop listening
+   */
+  onWalletChange(cb) {
+    return this._engine.onWalletChange(cb);
+  }
+  /**
+   * Subscribe to chain changes (switchChain calls).
+   * Returns an unsubscribe function.
+   */
+  onChainChange(cb) {
+    return this._engine.onChainChange(cb);
+  }
   // ─── Contract API ───────────────────────────────────────────────────────────
   /**
    * Load a deployed contract and return a fully typed, ABI-powered instance.
@@ -785,6 +956,10 @@ Currently registered: ${registered}`
   }
 };
 
+Object.defineProperty(exports, "ChainMismatchError", {
+  enumerable: true,
+  get: function () { return walletEngine.ChainMismatchError; }
+});
 Object.defineProperty(exports, "ChainSwitchError", {
   enumerable: true,
   get: function () { return walletEngine.ChainSwitchError; }