@turnkey/core 1.0.0-beta.2 → 1.0.0-beta.5

package/dist/__wallet__/wallet-connect/base.d.ts

@@ -8,14 +8,28 @@ export declare class WalletConnectWallet implements WalletConnectInterface {
     private ethChain;
     private solChain;
     private uri?;
+    private changeListeners;
+    private addChangeListener;
+    private notifyChange;
+    /**
+     * Constructs a WalletConnectWallet bound to a WalletConnect client.
+     *
+     * - Subscribes to session deletions and automatically re-initiates pairing,
+     *   updating `this.uri` so the UI can present a fresh QR/deeplink.
+     *
+     * @param client - The low-level WalletConnect client used for session/RPC.
+     */
     constructor(client: WalletConnectClient);
     /**
-     * Initializes WalletConnect pairing flow with the specified chains.
-     * If an active session already exists, pairing is skipped.
+     * Initializes WalletConnect pairing flow with the specified namespaces.
+     *
+     * - Saves the requested chain namespaces (e.g., `["eip155:1", "eip155:137", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"]`).
+     * - If an active session already has connected accounts, pairing is skipped.
+     * - Otherwise initiates a pairing and stores the resulting URI.
      *
-     * @param opts.ethereum - Whether to enable Ethereum pairing
-     * @param opts.solana - Whether to enable Solana pairing
-     * @throws {Error} If no chains are enabled
+     * @param opts.ethereumNamespaces - List of EVM CAIP IDs (e.g., "eip155:1").
+     * @param opts.solanaNamespaces - List of Solana CAIP IDs (e.g., "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp").
+     * @throws {Error} If no namespaces are provided for either chain.
      */
     init(opts: {
         ethereumNamespaces: string[];
@@ -23,61 +37,130 @@ export declare class WalletConnectWallet implements WalletConnectInterface {
     }): Promise<void>;
     /**
      * Returns WalletConnect providers with associated chain/account metadata.
+     *
+     * - Builds an EVM provider (if Ethereum namespaces are enabled).
+     * - Builds a Solana provider (if Solana namespaces are enabled).
+     *
+     * @returns A promise resolving to an array of WalletProvider objects.
      */
     getProviders(): Promise<WalletProvider[]>;
     /**
      * Approves the session if needed and ensures at least one account is available.
+     *
+     * - Calls `approve()` on the underlying client when pairing is pending.
+     * - Throws if the approved session contains no connected accounts.
+     *
+     * @param _provider - Unused (present for interface compatibility).
+     * @throws {Error} If the session contains no accounts.
      */
     connectWalletAccount(_provider: WalletProvider): Promise<void>;
     /**
-     * Switch the user’s WalletConnect session to a new EVM chain.
+     * Switches the user’s WalletConnect session to a new EVM chain.
      *
-     * @param provider   – the WalletProvider returned by getProviders()
-     * @param chainOrId  – either:
-     *                     • a CAIP string ("eip155:1", "eip155:137", …)
-     *                     • a SwitchableChain object carrying full metadata
+     * - Ethereum-only: only supported for providers on the Ethereum namespace.
+     * - No add-then-switch: WalletConnect cannot add chains mid-session. The target chain
+     *   must be present in `ethereumNamespaces` negotiated at pairing time. To support a new chain,
+     *   you must include it in the walletConfig.
+     * - Accepts a hex chain ID (e.g., "0x1"). If a `SwitchableChain` is passed, only its `id`
+     *   (hex chain ID) is used; metadata is ignored for WalletConnect.
+     *
+     * @param provider - The WalletProvider returned by `getProviders()`.
+     * @param chainOrId - Hex chain ID (e.g., "0x1") or a `SwitchableChain` (its `id` is used).
+     * @returns A promise that resolves when the switch completes.
+     * @throws {Error} If no active session, provider is non-EVM, the chain is not in `ethereumNamespaces`,
+     *                 or the switch RPC fails.
      */
     switchChain(provider: WalletProvider, chainOrId: string | SwitchableChain): Promise<void>;
     /**
-     * Signs a message or transaction using the specified provider and intent.
+     * Signs a message or transaction using the specified wallet provider and intent.
+     *
+     * - Ensures an active WalletConnect session:
+     *   - If a pairing is in progress (URI shown but not yet approved), this call will
+     *     wait for the user to approve the session and may appear stuck until they do.
+     *   - If no pairing is in progress, this will throw (e.g., "call pair() before approve()").
+     * - Ethereum:
+     *   - `SignMessage` → `personal_sign` (returns hex signature).
+     *   - `SignAndSendTransaction` → `eth_sendTransaction` (returns tx hash).
+     * - Solana:
+     *   - `SignMessage` → `solana_signMessage` (returns hex signature).
+     *   - `SignTransaction` → `solana_signTransaction` (returns hex signature).
+     *   - `SignAndSendTransaction` → `solana_sendTransaction` (returns hex signature of the submitted tx).
      *
-     * @param message - The message or serialized transaction to sign.
+     * @param payload - Payload or serialized transaction to sign.
      * @param provider - The WalletProvider to use.
-     * @param intent - The type of signing intent (message, tx, send).
+     * @param intent - The signing intent.
+     * @returns A hex string (signature or transaction hash, depending on intent).
+     * @throws {Error} If no account is available, no pairing is in progress, or the intent is unsupported.
      */
-    sign(message: string, provider: WalletProvider, intent: SignIntent): Promise<string>;
+    sign(payload: string, provider: WalletProvider, intent: SignIntent): Promise<string>;
     /**
      * Retrieves the public key of the connected wallet.
      *
+     * - Ethereum: signs a fixed challenge and recovers the compressed secp256k1 public key.
+     * - Solana: decodes the base58-encoded address to raw bytes.
+     *
      * @param provider - The WalletProvider to fetch the key from.
-     * @returns Compressed public key as a hex string.
+     * @returns A compressed public key as a hex string.
+     * @throws {Error} If no account is available or the namespace is unsupported.
      */
     getPublicKey(provider: WalletProvider): Promise<string>;
     /**
      * Disconnects the current session and re-initiates a fresh pairing URI.
+     *
+     * - Calls `disconnect()` on the client, then `pair()` with current namespaces.
+     * - Updates `this.uri` so the UI can present a new QR/deeplink.
      */
     disconnectWalletAccount(_provider: WalletProvider): Promise<void>;
     /**
      * Builds a lightweight provider interface for the given chain.
      *
-     * @param chainId - The namespace chain ID (e.g., eip155:1)
-     * @returns A WalletConnect-compatible provider implementation
+     * @param chainId - Namespace chain ID (e.g., "eip155:1" or "solana:101").
+     * @returns A WalletConnect-compatible provider that proxies JSON-RPC via WC.
      */
     private makeProvider;
     /**
      * Ensures there is an active WalletConnect session, initiating approval if necessary.
      *
-     * @returns The current WalletConnect session
-     * @throws {Error} If approval fails or session is not established
+     * - If a session exists, returns it immediately.
+     * - If no session exists but a pairing is in progress, awaits `approve()` —
+     *   this will block until the user approves (or rejects) in their wallet.
+     * - If no session exists and no pairing is in progress, throws; the caller
+     *   must have initiated pairing via `pair()` elsewhere.
+     *
+     * @returns The active WalletConnect session.
+     * @throws {Error} If approval is rejected, completes without establishing a session,
+     *                 or no pairing is in progress.
      */
     private ensureSession;
     /**
      * Builds a WalletProvider descriptor for an EVM chain.
+     *
+     * - Extracts the connected address (if any) and current chain ID.
+     * - Includes the pairing `uri` if available.
+     *
+     * @param session - Current WalletConnect session (or null).
+     * @param info - Provider branding info (name, icon).
+     * @returns A WalletProvider object for Ethereum.
      */
     private buildEthProvider;
     /**
      * Builds a WalletProvider descriptor for Solana.
+     *
+     * - Extracts the connected address (if any).
+     * - Includes the fresh pairing `uri` if available.
+     *
+     * @param session - Current WalletConnect session (or null).
+     * @param info - Provider branding info (name, icon).
+     * @returns A WalletProvider object for Solana.
      */
     private buildSolProvider;
+    /**
+     * Builds the requested WalletConnect namespaces from the current config.
+     *
+     * - Includes methods and events for Ethereum and/or Solana based on enabled namespaces.
+     *
+     * @returns A namespaces object suitable for `WalletConnectClient.pair()`.
+     */
+    private buildNamespaces;
 }
 //# sourceMappingURL=base.d.ts.map

package/dist/__wallet__/wallet-connect/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/__wallet__/wallet-connect/base.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,mBAAmB,EACnB,cAAc,EAEd,UAAU,EAEV,sBAAsB,EACtB,eAAe,EAChB,MAAM,QAAQ,CAAC;AAChB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIpD,qBAAa,mBAAoB,YAAW,sBAAsB;IAWpD,OAAO,CAAC,MAAM;IAV1B,QAAQ,CAAC,aAAa,qCAAqC;IAE3D,OAAO,CAAC,kBAAkB,CAAgB;IAC1C,OAAO,CAAC,gBAAgB,CAAgB;IAExC,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,QAAQ,CAAU;IAE1B,OAAO,CAAC,GAAG,CAAC,CAAS;gBAED,MAAM,EAAE,mBAAmB;IAI/C;;;;;;;OAOG;IACG,IAAI,CAAC,IAAI,EAAE;QACf,kBAAkB,EAAE,MAAM,EAAE,CAAC;QAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAC;KAC5B,GAAG,OAAO,CAAC,IAAI,CAAC;IAwDjB;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAqB/C;;OAEG;IACG,oBAAoB,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpE;;;;;;;OAOG;IACG,WAAW,CACf,QAAQ,EAAE,cAAc,EACxB,SAAS,EAAE,MAAM,GAAG,eAAe,GAClC,OAAO,CAAC,IAAI,CAAC;IAmChB;;;;;;OAMG;IACG,IAAI,CACR,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,MAAM,CAAC;IAuGlB;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAyC7D;;OAEG;IACG,uBAAuB,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCvE;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;YACW,aAAa;IAU3B;;OAEG;YACW,gBAAgB;IAwB9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAgBzB"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/__wallet__/wallet-connect/base.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,mBAAmB,EACnB,cAAc,EAEd,UAAU,EAEV,sBAAsB,EACtB,eAAe,EAChB,MAAM,QAAQ,CAAC;AAChB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AASpD,qBAAa,mBAAoB,YAAW,sBAAsB;IAkCpD,OAAO,CAAC,MAAM;IAjC1B,QAAQ,CAAC,aAAa,qCAAqC;IAE3D,OAAO,CAAC,kBAAkB,CAAgB;IAC1C,OAAO,CAAC,gBAAgB,CAAgB;IAExC,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,QAAQ,CAAU;IAE1B,OAAO,CAAC,GAAG,CAAC,CAAS;IAErB,OAAO,CAAC,eAAe,CAEnB;IAEJ,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,YAAY;IAIpB;;;;;;;OAOG;gBACiB,MAAM,EAAE,mBAAmB;IAuB/C;;;;;;;;;;OAUG;IACG,IAAI,CAAC,IAAI,EAAE;QACf,kBAAkB,EAAE,MAAM,EAAE,CAAC;QAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAC;KAC5B,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCjB;;;;;;;OAOG;IACG,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAqB/C;;;;;;;;OAQG;IACG,oBAAoB,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpE;;;;;;;;;;;;;;;OAeG;IACG,WAAW,CACf,QAAQ,EAAE,cAAc,EACxB,SAAS,EAAE,MAAM,GAAG,eAAe,GAClC,OAAO,CAAC,IAAI,CAAC;IAmChB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,IAAI,CACR,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,MAAM,CAAC;IAuGlB;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAyC7D;;;;;OAKG;IACG,uBAAuB,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvE;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAepB;;;;;;;;;;;;OAYG;YACW,aAAa;IAU3B;;;;;;;;;OASG;YACW,gBAAgB;IAwB9B;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;CA+BxB"}

package/dist/__wallet__/wallet-connect/base.js

@@ -8,20 +8,55 @@ var base = require('../../__types__/base.js');
 var ethers = require('ethers');
 
 class WalletConnectWallet {
+    addChangeListener(listener) {
+        this.changeListeners.add(listener);
+        return () => this.changeListeners.delete(listener);
+    }
+    notifyChange(event) {
+        this.changeListeners.forEach((listener) => listener(event));
+    }
+    /**
+     * Constructs a WalletConnectWallet bound to a WalletConnect client.
+     *
+     * - Subscribes to session deletions and automatically re-initiates pairing,
+     *   updating `this.uri` so the UI can present a fresh QR/deeplink.
+     *
+     * @param client - The low-level WalletConnect client used for session/RPC.
+     */
     constructor(client) {
         this.client = client;
         this.interfaceType = base.WalletInterfaceType.WalletConnect;
         this.ethereumNamespaces = [];
         this.solanaNamespaces = [];
-        this.client.onSessionDelete(() => { });
+        this.changeListeners = new Set();
+        // session disconnected
+        this.client.onSessionDelete(() => {
+            this.notifyChange({ type: "disconnect" });
+        });
+        // session updated (actual update to the session for example adding a chain to namespaces)
+        this.client.onSessionUpdate(() => {
+            this.notifyChange({ type: "update" });
+        });
+        // chain switched
+        this.client.onSessionEvent(({ event }) => {
+            if (event?.name === "chainChanged" || event?.name === "accountsChanged") {
+                const chainId = typeof event.data?.chainId === "string"
+                    ? event.data.chainId
+                    : undefined;
+                this.notifyChange({ type: "chainChanged", chainId });
+            }
+        });
     }
     /**
-     * Initializes WalletConnect pairing flow with the specified chains.
-     * If an active session already exists, pairing is skipped.
+     * Initializes WalletConnect pairing flow with the specified namespaces.
      *
-     * @param opts.ethereum - Whether to enable Ethereum pairing
-     * @param opts.solana - Whether to enable Solana pairing
-     * @throws {Error} If no chains are enabled
+     * - Saves the requested chain namespaces (e.g., `["eip155:1", "eip155:137", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"]`).
+     * - If an active session already has connected accounts, pairing is skipped.
+     * - Otherwise initiates a pairing and stores the resulting URI.
+     *
+     * @param opts.ethereumNamespaces - List of EVM CAIP IDs (e.g., "eip155:1").
+     * @param opts.solanaNamespaces - List of Solana CAIP IDs (e.g., "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp").
+     * @throws {Error} If no namespaces are provided for either chain.
      */
     async init(opts) {
         this.ethereumNamespaces = opts.ethereumNamespaces;
@@ -36,39 +71,23 @@ class WalletConnectWallet {
             this.solanaNamespaces.length === 0) {
             throw new Error("At least one namespace must be enabled for WalletConnect");
         }
+        // we don't want to create more than one active session
+        // so we don't make a pair request if one is already active
+        // since pairing would mean initializing a new session
         const session = this.client.getSession();
         if (hasConnectedAccounts(session)) {
             return;
         }
-        const namespaces = {};
-        if (this.ethereumNamespaces.length > 0) {
-            namespaces.eip155 = {
-                methods: [
-                    "personal_sign",
-                    "eth_sendTransaction",
-                    "eth_chainId",
-                    "wallet_switchEthereumChain",
-                    "wallet_addEthereumChain",
-                ],
-                chains: this.ethereumNamespaces,
-                events: ["accountsChanged", "chainChanged"],
-            };
-        }
-        if (this.solanaNamespaces.length > 0) {
-            namespaces.solana = {
-                methods: [
-                    "solana_signMessage",
-                    "solana_signTransaction",
-                    "solana_sendTransaction",
-                ],
-                chains: this.solanaNamespaces,
-                events: ["accountsChanged", "chainChanged"],
-            };
-        }
+        const namespaces = this.buildNamespaces();
         this.uri = await this.client.pair(namespaces);
     }
     /**
      * Returns WalletConnect providers with associated chain/account metadata.
+     *
+     * - Builds an EVM provider (if Ethereum namespaces are enabled).
+     * - Builds a Solana provider (if Solana namespaces are enabled).
+     *
+     * @returns A promise resolving to an array of WalletProvider objects.
      */
     async getProviders() {
         const session = this.client.getSession();
@@ -87,6 +106,12 @@ class WalletConnectWallet {
     }
     /**
      * Approves the session if needed and ensures at least one account is available.
+     *
+     * - Calls `approve()` on the underlying client when pairing is pending.
+     * - Throws if the approved session contains no connected accounts.
+     *
+     * @param _provider - Unused (present for interface compatibility).
+     * @throws {Error} If the session contains no accounts.
      */
     async connectWalletAccount(_provider) {
         const session = await this.client.approve();
@@ -94,12 +119,20 @@ class WalletConnectWallet {
             throw new Error("No account found in session");
     }
     /**
-     * Switch the user’s WalletConnect session to a new EVM chain.
+     * Switches the user’s WalletConnect session to a new EVM chain.
+     *
+     * - Ethereum-only: only supported for providers on the Ethereum namespace.
+     * - No add-then-switch: WalletConnect cannot add chains mid-session. The target chain
+     *   must be present in `ethereumNamespaces` negotiated at pairing time. To support a new chain,
+     *   you must include it in the walletConfig.
+     * - Accepts a hex chain ID (e.g., "0x1"). If a `SwitchableChain` is passed, only its `id`
+     *   (hex chain ID) is used; metadata is ignored for WalletConnect.
      *
-     * @param provider   – the WalletProvider returned by getProviders()
-     * @param chainOrId  – either:
-     *                     • a CAIP string ("eip155:1", "eip155:137", …)
-     *                     • a SwitchableChain object carrying full metadata
+     * @param provider - The WalletProvider returned by `getProviders()`.
+     * @param chainOrId - Hex chain ID (e.g., "0x1") or a `SwitchableChain` (its `id` is used).
+     * @returns A promise that resolves when the switch completes.
+     * @throws {Error} If no active session, provider is non-EVM, the chain is not in `ethereumNamespaces`,
+     *                 or the switch RPC fails.
      */
     async switchChain(provider, chainOrId) {
         if (provider.chainInfo.namespace !== base.Chain.Ethereum) {
@@ -126,13 +159,27 @@ class WalletConnectWallet {
         }
     }
     /**
-     * Signs a message or transaction using the specified provider and intent.
+     * Signs a message or transaction using the specified wallet provider and intent.
      *
-     * @param message - The message or serialized transaction to sign.
+     * - Ensures an active WalletConnect session:
+     *   - If a pairing is in progress (URI shown but not yet approved), this call will
+     *     wait for the user to approve the session and may appear stuck until they do.
+     *   - If no pairing is in progress, this will throw (e.g., "call pair() before approve()").
+     * - Ethereum:
+     *   - `SignMessage` → `personal_sign` (returns hex signature).
+     *   - `SignAndSendTransaction` → `eth_sendTransaction` (returns tx hash).
+     * - Solana:
+     *   - `SignMessage` → `solana_signMessage` (returns hex signature).
+     *   - `SignTransaction` → `solana_signTransaction` (returns hex signature).
+     *   - `SignAndSendTransaction` → `solana_sendTransaction` (returns hex signature of the submitted tx).
+     *
+     * @param payload - Payload or serialized transaction to sign.
      * @param provider - The WalletProvider to use.
-     * @param intent - The type of signing intent (message, tx, send).
+     * @param intent - The signing intent.
+     * @returns A hex string (signature or transaction hash, depending on intent).
+     * @throws {Error} If no account is available, no pairing is in progress, or the intent is unsupported.
      */
-    async sign(message, provider, intent) {
+    async sign(payload, provider, intent) {
         const session = await this.ensureSession();
         if (!hasConnectedAccounts(session)) {
             await this.connectWalletAccount(provider);
@@ -145,12 +192,12 @@ class WalletConnectWallet {
             switch (intent) {
                 case base.SignIntent.SignMessage:
                     return (await this.client.request(this.ethChain, "personal_sign", [
-                        message,
+                        payload,
                         address,
                     ]));
                 case base.SignIntent.SignAndSendTransaction:
                     const account = provider.connectedAddresses[0];
-                    const tx = ethers.Transaction.from(message);
+                    const tx = ethers.Transaction.from(payload);
                     const txParams = {
                         from: account,
                         to: tx.to?.toString(),
@@ -174,7 +221,7 @@ class WalletConnectWallet {
             }
             switch (intent) {
                 case base.SignIntent.SignMessage: {
-                    const msgBytes = new TextEncoder().encode(message);
+                    const msgBytes = new TextEncoder().encode(payload);
                     const msgB58 = bs58.encode(msgBytes);
                     const { signature: sigB58 } = await this.client.request(this.solChain, "solana_signMessage", {
                         pubkey: address,
@@ -183,7 +230,7 @@ class WalletConnectWallet {
                     return encoding.uint8ArrayToHexString(bs58.decode(sigB58));
                 }
                 case base.SignIntent.SignTransaction: {
-                    const txBytes = encoding.uint8ArrayFromHexString(message);
+                    const txBytes = encoding.uint8ArrayFromHexString(payload);
                     const txBase64 = encoding.stringToBase64urlString(String.fromCharCode(...txBytes));
                     const { signature: sigB58 } = await this.client.request(this.solChain, "solana_signTransaction", {
                         feePayer: address,
@@ -192,7 +239,7 @@ class WalletConnectWallet {
                     return encoding.uint8ArrayToHexString(bs58.decode(sigB58));
                 }
                 case base.SignIntent.SignAndSendTransaction: {
-                    const txBytes = encoding.uint8ArrayFromHexString(message);
+                    const txBytes = encoding.uint8ArrayFromHexString(payload);
                     const txBase64 = encoding.stringToBase64urlString(String.fromCharCode(...txBytes));
                     const sigB58 = await this.client.request(this.solChain, "solana_sendTransaction", {
                         feePayer: address,
@@ -210,8 +257,12 @@ class WalletConnectWallet {
     /**
      * Retrieves the public key of the connected wallet.
      *
+     * - Ethereum: signs a fixed challenge and recovers the compressed secp256k1 public key.
+     * - Solana: decodes the base58-encoded address to raw bytes.
+     *
      * @param provider - The WalletProvider to fetch the key from.
-     * @returns Compressed public key as a hex string.
+     * @returns A compressed public key as a hex string.
+     * @throws {Error} If no account is available or the namespace is unsupported.
      */
     async getPublicKey(provider) {
         const session = this.client.getSession();
@@ -247,34 +298,13 @@ class WalletConnectWallet {
     }
     /**
      * Disconnects the current session and re-initiates a fresh pairing URI.
+     *
+     * - Calls `disconnect()` on the client, then `pair()` with current namespaces.
+     * - Updates `this.uri` so the UI can present a new QR/deeplink.
      */
     async disconnectWalletAccount(_provider) {
         await this.client.disconnect();
-        const namespaces = {};
-        if (this.ethereumNamespaces.length > 0) {
-            namespaces.eip155 = {
-                methods: [
-                    "personal_sign",
-                    "eth_sendTransaction",
-                    "eth_chainId",
-                    "wallet_switchEthereumChain",
-                    "wallet_addEthereumChain",
-                ],
-                chains: this.ethereumNamespaces,
-                events: ["accountsChanged", "chainChanged"],
-            };
-        }
-        if (this.solanaNamespaces.length > 0) {
-            namespaces.solana = {
-                methods: [
-                    "solana_signMessage",
-                    "solana_signTransaction",
-                    "solana_sendTransaction",
-                ],
-                chains: this.solanaNamespaces,
-                events: ["accountsChanged", "chainChanged"],
-            };
-        }
+        const namespaces = this.buildNamespaces();
         await this.client.pair(namespaces).then((newUri) => {
             this.uri = newUri;
         });
@@ -282,21 +312,35 @@ class WalletConnectWallet {
     /**
      * Builds a lightweight provider interface for the given chain.
      *
-     * @param chainId - The namespace chain ID (e.g., eip155:1)
-     * @returns A WalletConnect-compatible provider implementation
+     * @param chainId - Namespace chain ID (e.g., "eip155:1" or "solana:101").
+     * @returns A WalletConnect-compatible provider that proxies JSON-RPC via WC.
      */
     makeProvider(chainId) {
         return {
-            request: ({ method, params }) => {
-                return this.client.request(chainId, method, params);
+            request: ({ method, params }) => this.client.request(chainId, method, params),
+            features: {
+                "standard:events": {
+                    on: (event, callback) => {
+                        if (event !== "change")
+                            return () => { };
+                        return this.addChangeListener(callback);
+                    },
+                },
             },
         };
     }
     /**
      * Ensures there is an active WalletConnect session, initiating approval if necessary.
      *
-     * @returns The current WalletConnect session
-     * @throws {Error} If approval fails or session is not established
+     * - If a session exists, returns it immediately.
+     * - If no session exists but a pairing is in progress, awaits `approve()` —
+     *   this will block until the user approves (or rejects) in their wallet.
+     * - If no session exists and no pairing is in progress, throws; the caller
+     *   must have initiated pairing via `pair()` elsewhere.
+     *
+     * @returns The active WalletConnect session.
+     * @throws {Error} If approval is rejected, completes without establishing a session,
+     *                 or no pairing is in progress.
      */
     async ensureSession() {
         let session = this.client.getSession();
@@ -310,6 +354,13 @@ class WalletConnectWallet {
     }
     /**
      * Builds a WalletProvider descriptor for an EVM chain.
+     *
+     * - Extracts the connected address (if any) and current chain ID.
+     * - Includes the pairing `uri` if available.
+     *
+     * @param session - Current WalletConnect session (or null).
+     * @param info - Provider branding info (name, icon).
+     * @returns A WalletProvider object for Ethereum.
      */
     async buildEthProvider(session, info) {
         const raw = session?.namespaces.eip155?.accounts?.[0] ?? "";
@@ -331,6 +382,13 @@ class WalletConnectWallet {
     }
     /**
      * Builds a WalletProvider descriptor for Solana.
+     *
+     * - Extracts the connected address (if any).
+     * - Includes the fresh pairing `uri` if available.
+     *
+     * @param session - Current WalletConnect session (or null).
+     * @param info - Provider branding info (name, icon).
+     * @returns A WalletProvider object for Solana.
      */
     buildSolProvider(session, info) {
         const raw = session?.namespaces.solana?.accounts?.[0] ?? "";
@@ -344,15 +402,78 @@ class WalletConnectWallet {
             ...(this.uri && { uri: this.uri }),
         };
     }
+    /**
+     * Builds the requested WalletConnect namespaces from the current config.
+     *
+     * - Includes methods and events for Ethereum and/or Solana based on enabled namespaces.
+     *
+     * @returns A namespaces object suitable for `WalletConnectClient.pair()`.
+     */
+    buildNamespaces() {
+        const namespaces = {};
+        if (this.ethereumNamespaces.length > 0) {
+            namespaces.eip155 = {
+                methods: [
+                    "personal_sign",
+                    "eth_sendTransaction",
+                    "eth_chainId",
+                    "wallet_switchEthereumChain",
+                    "wallet_addEthereumChain",
+                ],
+                chains: this.ethereumNamespaces,
+                events: ["accountsChanged", "chainChanged"],
+            };
+        }
+        if (this.solanaNamespaces.length > 0) {
+            namespaces.solana = {
+                methods: [
+                    "solana_signMessage",
+                    "solana_signTransaction",
+                    "solana_sendTransaction",
+                ],
+                chains: this.solanaNamespaces,
+                events: ["accountsChanged", "chainChanged"],
+            };
+        }
+        return namespaces;
+    }
 }
+/**
+ * Determines whether the session has at least one connected account
+ * across any namespace.
+ *
+ * - Safe to call with `null` (returns `false`).
+ * - Checks all namespaces for a non-empty `accounts` array.
+ *
+ * @param session - The current WalletConnect session, or `null`.
+ * @returns `true` if any namespace has ≥1 account; otherwise `false`.
+ */
 function hasConnectedAccounts(session) {
     return (!!session &&
         Object.values(session.namespaces).some((ns) => ns.accounts?.length > 0));
 }
+/**
+ * Retrieves the first connected Ethereum account.
+ *
+ * - Safe to call with `null` (returns `undefined`).
+ * - Returns only the address portion (e.g., `0xabc...`), not the full CAIP string.
+ *
+ * @param session - The current WalletConnect session, or `null`.
+ * @returns The connected EVM address, or `undefined` if none.
+ */
 function getConnectedEthereum(session) {
     const acc = session?.namespaces.eip155?.accounts?.[0];
     return acc ? acc.split(":")[2] : undefined;
 }
+/**
+ * Retrieves the first connected Solana account.
+ *
+ * - Safe to call with `null` (returns `undefined`).
+ * - Returns only the base58 address portion, not the full CAIP string.
+ *
+ * @param session - The current WalletConnect session, or `null`.
+ * @returns The connected Solana address (base58), or `undefined` if none.
+ */
 function getConnectedSolana(session) {
     const acc = session?.namespaces.solana?.accounts?.[0];
     return acc ? acc.split(":")[2] : undefined;