@meshconnect/uwc-wallet-connect-connector 0.6.4 → 0.7.0

package/dist/services/walletconnect-client.d.ts

@@ -1,13 +1,26 @@
 import SignClient from '@walletconnect/sign-client';
 import type { WalletConnectConfig } from '@meshconnect/uwc-types';
+/**
+ * Cap on distinct relay-error messages remembered for dedup. Dedup is a storm
+ * guard, not a permanent ledger — bounding it keeps memory flat on a long-lived
+ * session even if messages are high-cardinality (timestamps / urls).
+ */
+export declare const MAX_REPORTED_RELAY_ERRORS = 100;
 /**
  * Service for managing WalletConnect client instance
  */
 export declare class WalletConnectClient {
     private config;
+    private onRelayError?;
     private client;
     private initPromise;
-    constructor(config: WalletConnectConfig);
+    /** Dedupe relay-error reports so a reconnect storm surfaces once, not per tick. */
+    private readonly relayErrorDedup;
+    /**
+     * @param onRelayError - optional telemetry sink for relay-socket failures (see
+     *   `attachRelayErrorListener`). Opt-in: with nothing wired, behaviour is unchanged.
+     */
+    constructor(config: WalletConnectConfig, onRelayError?: ((error: unknown) => void) | undefined);
     /**
      * Initialize or get the WalletConnect client
      */
@@ -16,6 +29,23 @@ export declare class WalletConnectClient {
      * Initialize the WalletConnect client
      */
     private initClient;
+    /**
+     * Surface relay-socket failures as telemetry. The relay JsonRpcProvider re-emits
+     * an abnormal WebSocket close under `RELAYER_EVENTS.error` — e.g. close code 3000
+     * "JWT Token is not yet valid" when the device clock is skewed past the relay's
+     * 120s leeway. That error is otherwise detached from the connect() promise, so it
+     * escapes the connect handoff and lands as an unhandled error. Forward it (deduped
+     * per message) so it becomes a classified signal instead. `error` only —
+     * `connection_stalled` / `transport_closed` fire on transient blips and would add
+     * noise. Telemetry-only; it never changes connection behaviour.
+     */
+    private attachRelayErrorListener;
+    /**
+     * The initialized client if `connect()` already ran, else null. Synchronous —
+     * lets callers attach lifecycle listeners post-connect without forcing a
+     * re-init or awaiting.
+     */
+    getExistingClient(): SignClient | null;
     /**
      * Disconnect all sessions
      */

package/dist/services/walletconnect-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walletconnect-client.d.ts","sourceRoot":"","sources":["../../src/services/walletconnect-client.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,4BAA4B,CAAA;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAEjE;;GAEG;AACH,qBAAa,mBAAmB;IAIlB,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,WAAW,CAAmC;gBAElC,MAAM,EAAE,mBAAmB;IAE/C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;IAmBtC;;OAEG;YACW,UAAU;IA6BxB;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBpC;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAW/C"}
+{"version":3,"file":"walletconnect-client.d.ts","sourceRoot":"","sources":["../../src/services/walletconnect-client.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,4BAA4B,CAAA;AAGnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAEjE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAE5C;;GAEG;AACH,qBAAa,mBAAmB;IAa5B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,YAAY,CAAC;IAbvB,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,WAAW,CAAmC;IACtD,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAE/B;IAED;;;OAGG;gBAEO,MAAM,EAAE,mBAAmB,EAC3B,YAAY,CAAC,GAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,aAAA;IAGjD;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;IAmBtC;;OAEG;YACW,UAAU;IA+BxB;;;;;;;;;OASG;IACH,OAAO,CAAC,wBAAwB;IAkBhC;;;;OAIG;IACH,iBAAiB,IAAI,UAAU,GAAG,IAAI;IAItC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBpC;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAW/C"}

package/dist/services/walletconnect-client.js

@@ -1,13 +1,29 @@
 import SignClient from '@walletconnect/sign-client';
+import { RELAYER_EVENTS } from '@walletconnect/core';
+import { createBoundedDedup, safeErrorMessage } from '@meshconnect/uwc-types';
+/**
+ * Cap on distinct relay-error messages remembered for dedup. Dedup is a storm
+ * guard, not a permanent ledger — bounding it keeps memory flat on a long-lived
+ * session even if messages are high-cardinality (timestamps / urls).
+ */
+export const MAX_REPORTED_RELAY_ERRORS = 100;
 /**
  * Service for managing WalletConnect client instance
  */
 export class WalletConnectClient {
     config;
+    onRelayError;
     client = null;
     initPromise = null;
-    constructor(config) {
+    /** Dedupe relay-error reports so a reconnect storm surfaces once, not per tick. */
+    relayErrorDedup = createBoundedDedup(MAX_REPORTED_RELAY_ERRORS);
+    /**
+     * @param onRelayError - optional telemetry sink for relay-socket failures (see
+     *   `attachRelayErrorListener`). Opt-in: with nothing wired, behaviour is unchanged.
+     */
+    constructor(config, onRelayError) {
         this.config = config;
+        this.onRelayError = onRelayError;
     }
     /**
      * Initialize or get the WalletConnect client
@@ -52,8 +68,47 @@ export class WalletConnectClient {
             projectId: this.config.projectId,
             metadata
         });
+        this.attachRelayErrorListener(client);
         return client;
     }
+    /**
+     * Surface relay-socket failures as telemetry. The relay JsonRpcProvider re-emits
+     * an abnormal WebSocket close under `RELAYER_EVENTS.error` — e.g. close code 3000
+     * "JWT Token is not yet valid" when the device clock is skewed past the relay's
+     * 120s leeway. That error is otherwise detached from the connect() promise, so it
+     * escapes the connect handoff and lands as an unhandled error. Forward it (deduped
+     * per message) so it becomes a classified signal instead. `error` only —
+     * `connection_stalled` / `transport_closed` fire on transient blips and would add
+     * noise. Telemetry-only; it never changes connection behaviour.
+     */
+    attachRelayErrorListener(client) {
+        if (!this.onRelayError)
+            return;
+        client.core?.relayer?.on(RELAYER_EVENTS.error, (error) => {
+            // safeErrorMessage: this runs INSIDE the SDK's relayer dispatch, before
+            // the sink guard below — a throwing toString() here would break the
+            // emitter just like a throwing sink; the dedup key stays bounded too.
+            const message = safeErrorMessage(error);
+            if (!this.relayErrorDedup.firstSeen(message))
+                return;
+            try {
+                this.onRelayError?.(error);
+            }
+            catch {
+                // A throwing sink would propagate synchronously out of the WC SDK's
+                // relayer emitter and prevent its own error handling (transportClose)
+                // from running. Telemetry must never break the relay.
+            }
+        });
+    }
+    /**
+     * The initialized client if `connect()` already ran, else null. Synchronous —
+     * lets callers attach lifecycle listeners post-connect without forcing a
+     * re-init or awaiting.
+     */
+    getExistingClient() {
+        return this.client;
+    }
     /**
      * Disconnect all sessions
      */

package/dist/services/walletconnect-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"walletconnect-client.js","sourceRoot":"","sources":["../../src/services/walletconnect-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"walletconnect-client.js","sourceRoot":"","sources":["../../src/services/walletconnect-client.ts"],"names":[],"mappings":"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"}

package/dist/wallet-connect-connector.d.ts

@@ -1,4 +1,4 @@
-import type { Network, Connector, ConnectorResult, SwitchNetworkResult, WalletConnectConfig, WalletConnectProvider, TransactionRequest, TransactionResult, NetworkRpcMap, SignatureType, EIP712TypedData } from '@meshconnect/uwc-types';
+import type { Network, Connector, ConnectorResult, SwitchNetworkResult, WalletConnectConfig, WalletConnectProvider, TransactionRequest, TransactionResult, NetworkRpcMap, SignatureType, EIP712TypedData, WalletLifecycleEvent, WalletLifecycleContext } from '@meshconnect/uwc-types';
 export declare class WalletConnectConnector implements Connector {
     private walletConnectClient;
     private connectionService;
@@ -6,7 +6,7 @@ export declare class WalletConnectConnector implements Connector {
     private signatureService;
     private transactionService;
     private networkRpcMap;
-    constructor(config: WalletConnectConfig, networkRpcMap?: NetworkRpcMap);
+    constructor(config: WalletConnectConfig, networkRpcMap?: NetworkRpcMap, onRelayError?: (error: unknown) => void);
     connect(network: Network, provider?: WalletConnectProvider): Promise<ConnectorResult>;
     getConnectionURI(): string;
     disconnect(): Promise<void>;
@@ -22,5 +22,24 @@ export declare class WalletConnectConnector implements Connector {
      * Used by fee-payer relay flows (Mesh BE owns broadcast); never broadcasts via the wallet.
      */
     signSolanaTransactionBytes(serializedTx: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Observe post-connect lifecycle from the WalletConnect SignClient. Unlike the
+     * injected path, the SignClient lives IN this context (its own relay, not the
+     * iframe bridge), so this works in the production iframe too — no bridge needed.
+     *
+     * Maps the verified SignClient events (`@walletconnect/types`): `session_delete`
+     * → disconnect, `session_expire` → sessionExpired, and `session_event` (CAIP
+     * `accountsChanged` / `chainChanged`, the latter normalized to CAIP-2 from
+     * `event.data` — see `toCaipChainId`). The account address in the event
+     * payload is never forwarded. Returns undefined before a session exists so
+     * the core reports lifecycle unavailable.
+     *
+     * TOPIC FILTER: SignClient events are client-global and WC v2 persists old
+     * sessions in storage, so a stale session expiring would otherwise surface as a
+     * phantom disconnect/expiry of the live one. Every payload carries a `topic`
+     * (`@walletconnect/types` BaseEventArgs); only the ACTIVE session's topic is
+     * forwarded, resolved per event so a restore/re-connect is honoured live.
+     */
+    onLifecycleEvent(listener: (event: WalletLifecycleEvent) => void, _context: WalletLifecycleContext): (() => void) | undefined;
 }
 //# sourceMappingURL=wallet-connect-connector.d.ts.map

package/dist/wallet-connect-connector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wallet-connect-connector.d.ts","sourceRoot":"","sources":["../src/wallet-connect-connector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,eAAe,EAChB,MAAM,wBAAwB,CAAA;AAO/B,qBAAa,sBAAuB,YAAW,SAAS;IACtD,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,iBAAiB,CAAmB;IAC5C,OAAO,CAAC,oBAAoB,CAAsB;IAClD,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,kBAAkB,CAAoB;IAC9C,OAAO,CAAC,aAAa,CAAe;gBAExB,MAAM,EAAE,mBAAmB,EAAE,aAAa,GAAE,aAAkB;IAmBpE,OAAO,CACX,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,OAAO,CAAC,eAAe,CAAC;IAU3B,gBAAgB,IAAI,MAAM;IAQpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI7D,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIpD,aAAa,CAAC,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D,eAAe,CACnB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC;IAI7B;;;;;;OAMG;IACG,0BAA0B,CAC9B,YAAY,EAAE,UAAU,GACvB,OAAO,CAAC,UAAU,CAAC;CAGvB"}
+{"version":3,"file":"wallet-connect-connector.d.ts","sourceRoot":"","sources":["../src/wallet-connect-connector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EAEP,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,wBAAwB,CAAA;AAsG/B,qBAAa,sBAAuB,YAAW,SAAS;IACtD,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,iBAAiB,CAAmB;IAC5C,OAAO,CAAC,oBAAoB,CAAsB;IAClD,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,kBAAkB,CAAoB;IAC9C,OAAO,CAAC,aAAa,CAAe;gBAGlC,MAAM,EAAE,mBAAmB,EAC3B,aAAa,GAAE,aAAkB,EACjC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAoBnC,OAAO,CACX,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,OAAO,CAAC,eAAe,CAAC;IAU3B,gBAAgB,IAAI,MAAM;IAQpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI7D,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIpD,aAAa,CAAC,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D,eAAe,CACnB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC;IAI7B;;;;;;OAMG;IACG,0BAA0B,CAC9B,YAAY,EAAE,UAAU,GACvB,OAAO,CAAC,UAAU,CAAC;IAItB;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CACd,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,EAI/C,QAAQ,EAAE,sBAAsB,GAC/B,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS;CA8C5B"}

package/dist/wallet-connect-connector.js

@@ -3,6 +3,104 @@ import { ConnectionService } from './services/connection-service';
 import { NetworkSwitchService } from './services/network-switch-service';
 import { SignatureService } from './services/signature-service';
 import { TransactionService } from './services/transaction-service';
+// The shape checks below are plain char loops, not regexes: the payload is
+// wallet-supplied, and the SAST gate fails the pipeline for ANY regex over
+// untrusted input (WS-I002-JAVASCRIPT-00082), linear-time or not.
+/** Non-empty and every char is a decimal digit. */
+function isDecimalString(value) {
+    if (value.length === 0)
+        return false;
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        if (c < 48 || c > 57)
+            return false;
+    }
+    return true;
+}
+/** `0x` followed by at least one hex digit, nothing else. */
+function isHexQuantity(value) {
+    if (value.length < 3 || !value.startsWith('0x'))
+        return false;
+    for (let i = 2; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        const hex = (c >= 48 && c <= 57) || (c >= 97 && c <= 102) || (c >= 65 && c <= 70);
+        if (!hex)
+            return false;
+    }
+    return true;
+}
+/**
+ * CAIP-2 shape: `[a-z0-9]{3,8}` namespace, one colon, `[-_a-zA-Z0-9]{1,32}`
+ * reference. The reference charset excludes `:`, so a second colon fails.
+ */
+function isCaip2ChainId(value) {
+    const colon = value.indexOf(':');
+    if (colon < 3 || colon > 8)
+        return false;
+    const referenceLength = value.length - colon - 1;
+    if (referenceLength < 1 || referenceLength > 32)
+        return false;
+    for (let i = 0; i < colon; i++) {
+        const c = value.charCodeAt(i);
+        if (!((c >= 48 && c <= 57) || (c >= 97 && c <= 122)))
+            return false;
+    }
+    for (let i = colon + 1; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        const ok = (c >= 48 && c <= 57) ||
+            (c >= 97 && c <= 122) ||
+            (c >= 65 && c <= 90) ||
+            c === 45 || // '-'
+            c === 95; // '_'
+        if (!ok)
+            return false;
+    }
+    return true;
+}
+/**
+ * Normalize a WC `session_event` chainChanged payload to CAIP-2. The NEW chain
+ * travels in `event.data` (hex / decimal string / number per the EIP-1193
+ * convention — WalletConnect's own EthereumProvider reads `event.data`); the
+ * sibling `params.chainId` is only the CAIP-2 scope the event was emitted
+ * under, i.e. potentially the PRE-switch chain, so it donates its namespace
+ * and nothing else. Unparseable data yields undefined — a content-free
+ * `chainChanged` beats a wrong chain id.
+ */
+function toCaipChainId(data, scope) {
+    if (typeof data === 'string' && isCaip2ChainId(data)) {
+        // Some wallets already send CAIP-2. An eip155 reference must be DECIMAL
+        // per CAIP-2, so a non-decimal ref (`eip155:0x1`) re-enters the numeric
+        // normalization below — the namespace survives via the `scope` argument.
+        // The shape check guarantees one colon with a non-empty tail; the
+        // fallback only satisfies noUncheckedIndexedAccess.
+        const [namespace, reference = ''] = data.split(':');
+        if (namespace !== 'eip155' || isDecimalString(reference)) {
+            return data;
+        }
+        return toCaipChainId(reference, data);
+    }
+    let decimal;
+    if (typeof data === 'string') {
+        // Full-shape match before converting: parseInt('0x1junk', 16) === 1.
+        if (isHexQuantity(data)) {
+            decimal = parseInt(data, 16);
+        }
+        else if (isDecimalString(data)) {
+            decimal = parseInt(data, 10);
+        }
+    }
+    else if (typeof data === 'number' && Number.isInteger(data) && data >= 0) {
+        decimal = data;
+    }
+    // isSafeInteger: beyond 2^53-1 parseInt has already lost precision —
+    // emitting a silently-wrong chain id is worse than emitting none.
+    if (decimal === undefined || !Number.isSafeInteger(decimal))
+        return undefined;
+    const namespace = typeof scope === 'string' && scope.includes(':')
+        ? scope.split(':')[0]
+        : 'eip155';
+    return `${namespace}:${decimal}`;
+}
 export class WalletConnectConnector {
     walletConnectClient;
     connectionService;
@@ -10,8 +108,8 @@ export class WalletConnectConnector {
     signatureService;
     transactionService;
     networkRpcMap;
-    constructor(config, networkRpcMap = {}) {
-        this.walletConnectClient = new WalletConnectClient(config);
+    constructor(config, networkRpcMap = {}, onRelayError) {
+        this.walletConnectClient = new WalletConnectClient(config, onRelayError);
         this.networkRpcMap = networkRpcMap;
         this.connectionService = new ConnectionService(this.walletConnectClient);
         this.networkSwitchService = new NetworkSwitchService(this.walletConnectClient, this.connectionService);
@@ -56,5 +154,66 @@ export class WalletConnectConnector {
     async signSolanaTransactionBytes(serializedTx) {
         return this.transactionService.signSolanaTransactionBytes(serializedTx);
     }
+    /**
+     * Observe post-connect lifecycle from the WalletConnect SignClient. Unlike the
+     * injected path, the SignClient lives IN this context (its own relay, not the
+     * iframe bridge), so this works in the production iframe too — no bridge needed.
+     *
+     * Maps the verified SignClient events (`@walletconnect/types`): `session_delete`
+     * → disconnect, `session_expire` → sessionExpired, and `session_event` (CAIP
+     * `accountsChanged` / `chainChanged`, the latter normalized to CAIP-2 from
+     * `event.data` — see `toCaipChainId`). The account address in the event
+     * payload is never forwarded. Returns undefined before a session exists so
+     * the core reports lifecycle unavailable.
+     *
+     * TOPIC FILTER: SignClient events are client-global and WC v2 persists old
+     * sessions in storage, so a stale session expiring would otherwise surface as a
+     * phantom disconnect/expiry of the live one. Every payload carries a `topic`
+     * (`@walletconnect/types` BaseEventArgs); only the ACTIVE session's topic is
+     * forwarded, resolved per event so a restore/re-connect is honoured live.
+     */
+    onLifecycleEvent(listener, 
+    // The active-session TOPIC (below) is the discriminator here — the context
+    // names the session but carries no topic, so it is accepted for contract
+    // parity and unused.
+    _context) {
+        const client = this.walletConnectClient.getExistingClient();
+        if (!client)
+            return undefined;
+        const isActiveTopic = (topic) => {
+            const active = this.connectionService.getSession()?.topic;
+            return active !== undefined && topic === active;
+        };
+        const onDelete = (args) => {
+            if (isActiveTopic(args?.topic))
+                listener({ type: 'disconnect' });
+        };
+        const onExpire = (args) => {
+            if (isActiveTopic(args?.topic))
+                listener({ type: 'sessionExpired' });
+        };
+        const onSessionEvent = (args) => {
+            if (!isActiveTopic(args?.topic))
+                return;
+            const name = args?.params?.event?.name;
+            if (name === 'accountsChanged') {
+                // Address dropped — signal THAT it changed, not which.
+                listener({ type: 'accountChanged' });
+            }
+            else if (name === 'chainChanged') {
+                // The new chain is in `event.data`; `params.chainId` is only the scope.
+                const chainId = toCaipChainId(args?.params?.event?.data, args?.params?.chainId);
+                listener(chainId ? { type: 'chainChanged', chainId } : { type: 'chainChanged' });
+            }
+        };
+        client.on('session_delete', onDelete);
+        client.on('session_expire', onExpire);
+        client.on('session_event', onSessionEvent);
+        return () => {
+            client.off('session_delete', onDelete);
+            client.off('session_expire', onExpire);
+            client.off('session_event', onSessionEvent);
+        };
+    }
 }
 //# sourceMappingURL=wallet-connect-connector.js.map

package/dist/wallet-connect-connector.js.map

@@ -1 +1 @@
-{"version":3,"file":"wallet-connect-connector.js","sourceRoot":"","sources":["../src/wallet-connect-connector.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAA;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAEnE,MAAM,OAAO,sBAAsB;IACzB,mBAAmB,CAAqB;IACxC,iBAAiB,CAAmB;IACpC,oBAAoB,CAAsB;IAC1C,gBAAgB,CAAkB;IAClC,kBAAkB,CAAoB;IACtC,aAAa,CAAe;IAEpC,YAAY,MAA2B,EAAE,gBAA+B,EAAE;QACxE,IAAI,CAAC,mBAAmB,GAAG,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAA;QAC1D,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;QAClC,IAAI,CAAC,iBAAiB,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;QACxE,IAAI,CAAC,oBAAoB,GAAG,IAAI,oBAAoB,CAClD,IAAI,CAAC,mBAAmB,EACxB,IAAI,CAAC,iBAAiB,CACvB,CAAA;QACD,IAAI,CAAC,gBAAgB,GAAG,IAAI,gBAAgB,CAC1C,IAAI,CAAC,mBAAmB,EACxB,IAAI,CAAC,iBAAiB,CACvB,CAAA;QACD,IAAI,CAAC,kBAAkB,GAAG,IAAI,kBAAkB,CAC9C,IAAI,CAAC,mBAAmB,EACxB,IAAI,CAAC,iBAAiB,EACtB,IAAI,CAAC,aAAa,CACnB,CAAA;IACH,CAAC;IAED,KAAK,CAAC,OAAO,CACX,OAAgB,EAChB,QAAgC;QAEhC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,gEAAgE,CACjE,CAAA;QACH,CAAC;QAED,OAAO,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IAC1D,CAAC;IAED,gBAAgB;QACd,MAAM,GAAG,GAAG,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,EAAE,CAAA;QACrD,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAA;QACvE,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,KAAK,CAAC,UAAU;QACd,OAAO,IAAI,CAAC,iBAAiB,CAAC,UAAU,EAAE,CAAA;IAC5C,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,OAAgB;QAClC,OAAO,IAAI,CAAC,oBAAoB,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IACzD,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,OAAe;QAC/B,OAAO,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;IACnD,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,SAA0B;QAC5C,OAAO,IAAI,CAAC,gBAAgB,CAAC,aAAa,CAAC,SAAS,CAAC,CAAA;IACvD,CAAC;IAED,KAAK,CAAC,eAAe,CACnB,OAA2B;QAE3B,OAAO,IAAI,CAAC,kBAAkB,CAAC,eAAe,CAAC,OAAO,CAAC,CAAA;IACzD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,0BAA0B,CAC9B,YAAwB;QAExB,OAAO,IAAI,CAAC,kBAAkB,CAAC,0BAA0B,CAAC,YAAY,CAAC,CAAA;IACzE,CAAC;CACF"}
+{"version":3,"file":"wallet-connect-connector.js","sourceRoot":"","sources":["../src/wallet-connect-connector.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshconnect/uwc-wallet-connect-connector",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "WalletConnect connector for Universal Wallet Connector",
   "type": "module",
   "main": "dist/index.js",
@@ -18,13 +18,14 @@
   "dependencies": {
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.4",
+    "@walletconnect/core": "^2.23.4",
     "@walletconnect/sign-client": "^2.23.4",
     "@walletconnect/types": "^2.23.4",
     "@walletconnect/utils": "^2.23.4",
     "bs58": "6.0.0",
     "buffer": "^6.0.3",
     "viem": "^2.44.4",
-    "@meshconnect/uwc-types": "0.16.1"
+    "@meshconnect/uwc-types": "0.17.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/services/walletconnect-client.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { WalletConnectConfig } from '@meshconnect/uwc-types'
+import { RELAYER_EVENTS } from '@walletconnect/core'
+
+// Relayer error handlers registered by the client under test, keyed by event name.
+const relayerHandlers: Record<string, (arg?: unknown) => void> = {}
+const fakeClient = {
+  core: {
+    relayer: {
+      on: (event: string, handler: (arg?: unknown) => void) => {
+        relayerHandlers[event] = handler
+      }
+    }
+  }
+}
+
+vi.mock('@walletconnect/sign-client', () => ({
+  default: { init: vi.fn(async () => fakeClient) }
+}))
+
+import {
+  WalletConnectClient,
+  MAX_REPORTED_RELAY_ERRORS
+} from './walletconnect-client'
+
+const CONFIG = { projectId: 'p' } as WalletConnectConfig
+
+describe('WalletConnectClient relay-error surfacing', () => {
+  beforeEach(() => {
+    for (const key of Object.keys(relayerHandlers)) delete relayerHandlers[key]
+  })
+
+  it('forwards a relayer error to onRelayError', async () => {
+    const errors: unknown[] = []
+    const client = new WalletConnectClient(CONFIG, e => errors.push(e))
+    await client.getClient()
+
+    relayerHandlers[RELAYER_EVENTS.error]?.(
+      new Error(
+        'WebSocket connection closed abnormally with code: 3000 (JWT validation error: JWT Token is not yet valid)'
+      )
+    )
+
+    expect(errors).toHaveLength(1)
+    expect((errors[0] as Error).message).toContain('3000')
+  })
+
+  it('dedupes repeated identical relay errors (reconnect storm → one report)', async () => {
+    const errors: unknown[] = []
+    const client = new WalletConnectClient(CONFIG, e => errors.push(e))
+    await client.getClient()
+
+    const fire = () =>
+      relayerHandlers[RELAYER_EVENTS.error]?.(new Error('same message'))
+    fire()
+    fire()
+    fire()
+
+    expect(errors).toHaveLength(1)
+  })
+
+  it('swallows a throwing onRelayError sink — must not break the relayer emitter', async () => {
+    const client = new WalletConnectClient(CONFIG, () => {
+      throw new Error('sink exploded')
+    })
+    await client.getClient()
+
+    // The handler runs inside the WC SDK's own relayer error dispatch — a
+    // propagating throw would prevent the SDK's transportClose from running.
+    expect(() =>
+      relayerHandlers[RELAYER_EVENTS.error]?.(new Error('relay down'))
+    ).not.toThrow()
+  })
+
+  it('never throws when the relayer emits a value with a throwing toString()', async () => {
+    const errors: unknown[] = []
+    const client = new WalletConnectClient(CONFIG, e => errors.push(e))
+    await client.getClient()
+
+    const evil = {
+      toString(): string {
+        throw new Error('poisoned toString')
+      }
+    }
+    // Message derivation runs inside the SDK's relayer dispatch, before the
+    // sink guard — it must be throw-proof too.
+    expect(() => relayerHandlers[RELAYER_EVENTS.error]?.(evil)).not.toThrow()
+    expect(errors).toHaveLength(1)
+  })
+
+  it('does not attach a relayer listener when no onRelayError is wired', async () => {
+    const client = new WalletConnectClient(CONFIG)
+    await expect(client.getClient()).resolves.toBeDefined()
+    expect(relayerHandlers[RELAYER_EVENTS.error]).toBeUndefined()
+  })
+
+  it('bounds the dedup set — an evicted message can report again past the cap', async () => {
+    const errors: unknown[] = []
+    const client = new WalletConnectClient(CONFIG, e => errors.push(e))
+    await client.getClient()
+    const fire = (m: string) =>
+      relayerHandlers[RELAYER_EVENTS.error]?.(new Error(m))
+
+    // Fill the set to the cap with distinct messages — each reports once.
+    for (let i = 0; i < MAX_REPORTED_RELAY_ERRORS; i++) fire(`err-${i}`)
+    expect(errors).toHaveLength(MAX_REPORTED_RELAY_ERRORS)
+
+    // Still deduped while in the set.
+    fire('err-0')
+    expect(errors).toHaveLength(MAX_REPORTED_RELAY_ERRORS)
+
+    // One more distinct message trips the cap → the set is evicted → it reports.
+    fire('over-cap')
+    expect(errors).toHaveLength(MAX_REPORTED_RELAY_ERRORS + 1)
+
+    // err-0 was evicted, so it reports again — proving the set stays bounded.
+    fire('err-0')
+    expect(errors).toHaveLength(MAX_REPORTED_RELAY_ERRORS + 2)
+  })
+})

package/src/services/walletconnect-client.ts

@@ -1,14 +1,34 @@
 import SignClient from '@walletconnect/sign-client'
+import { RELAYER_EVENTS } from '@walletconnect/core'
+import { createBoundedDedup, safeErrorMessage } from '@meshconnect/uwc-types'
 import type { WalletConnectConfig } from '@meshconnect/uwc-types'
 
+/**
+ * Cap on distinct relay-error messages remembered for dedup. Dedup is a storm
+ * guard, not a permanent ledger — bounding it keeps memory flat on a long-lived
+ * session even if messages are high-cardinality (timestamps / urls).
+ */
+export const MAX_REPORTED_RELAY_ERRORS = 100
+
 /**
  * Service for managing WalletConnect client instance
  */
 export class WalletConnectClient {
   private client: SignClient | null = null
   private initPromise: Promise<SignClient> | null = null
+  /** Dedupe relay-error reports so a reconnect storm surfaces once, not per tick. */
+  private readonly relayErrorDedup = createBoundedDedup(
+    MAX_REPORTED_RELAY_ERRORS
+  )
 
-  constructor(private config: WalletConnectConfig) {}
+  /**
+   * @param onRelayError - optional telemetry sink for relay-socket failures (see
+   *   `attachRelayErrorListener`). Opt-in: with nothing wired, behaviour is unchanged.
+   */
+  constructor(
+    private config: WalletConnectConfig,
+    private onRelayError?: (error: unknown) => void
+  ) {}
 
   /**
    * Initialize or get the WalletConnect client
@@ -61,9 +81,48 @@ export class WalletConnectClient {
       metadata
     })
 
+    this.attachRelayErrorListener(client)
+
     return client
   }
 
+  /**
+   * Surface relay-socket failures as telemetry. The relay JsonRpcProvider re-emits
+   * an abnormal WebSocket close under `RELAYER_EVENTS.error` — e.g. close code 3000
+   * "JWT Token is not yet valid" when the device clock is skewed past the relay's
+   * 120s leeway. That error is otherwise detached from the connect() promise, so it
+   * escapes the connect handoff and lands as an unhandled error. Forward it (deduped
+   * per message) so it becomes a classified signal instead. `error` only —
+   * `connection_stalled` / `transport_closed` fire on transient blips and would add
+   * noise. Telemetry-only; it never changes connection behaviour.
+   */
+  private attachRelayErrorListener(client: SignClient): void {
+    if (!this.onRelayError) return
+    client.core?.relayer?.on(RELAYER_EVENTS.error, (error: unknown) => {
+      // safeErrorMessage: this runs INSIDE the SDK's relayer dispatch, before
+      // the sink guard below — a throwing toString() here would break the
+      // emitter just like a throwing sink; the dedup key stays bounded too.
+      const message = safeErrorMessage(error)
+      if (!this.relayErrorDedup.firstSeen(message)) return
+      try {
+        this.onRelayError?.(error)
+      } catch {
+        // A throwing sink would propagate synchronously out of the WC SDK's
+        // relayer emitter and prevent its own error handling (transportClose)
+        // from running. Telemetry must never break the relay.
+      }
+    })
+  }
+
+  /**
+   * The initialized client if `connect()` already ran, else null. Synchronous —
+   * lets callers attach lifecycle listeners post-connect without forcing a
+   * re-init or awaiting.
+   */
+  getExistingClient(): SignClient | null {
+    return this.client
+  }
+
   /**
    * Disconnect all sessions
    */

package/src/wallet-connect-connector.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi } from 'vitest'
+import type {
+  WalletConnectConfig,
+  WalletLifecycleEvent
+} from '@meshconnect/uwc-types'
+import { WalletConnectConnector } from './wallet-connect-connector'
+
+const WC_CONTEXT = { connectionMode: 'walletConnect' as const }
+
+function mockSignClient() {
+  const handlers: Record<string, (a?: unknown) => void> = {}
+  return {
+    on: (e: string, h: (a?: unknown) => void) => {
+      handlers[e] = h
+    },
+    off: vi.fn((e: string) => {
+      delete handlers[e]
+    }),
+    fire: (e: string, arg?: unknown) => handlers[e]?.(arg)
+  }
+}
+
+function makeConnector(client: unknown) {
+  const connector = new WalletConnectConnector({
+    projectId: 'test'
+  } as WalletConnectConfig)
+  // Stub the post-connect client lookup (no real relay in a unit test).
+  ;(
+    connector as unknown as {
+      walletConnectClient: { getExistingClient: () => unknown }
+    }
+  ).walletConnectClient.getExistingClient = () => client
+  return connector
+}
+
+// The SignClient is client-global: its events fire for EVERY stored session
+// (WC v2 persists old sessions across page loads), so the lifecycle handlers
+// must filter by the ACTIVE session's topic. This helper plants the active
+// session the way `connect()` would.
+function setActiveTopic(connector: WalletConnectConnector, topic: string) {
+  ;(
+    connector as unknown as {
+      connectionService: { setSession: (s: unknown) => void }
+    }
+  ).connectionService.setSession({ topic })
+}
+
+describe('WalletConnectConnector.onLifecycleEvent', () => {
+  it('returns undefined before a session exists', () => {
+    expect(
+      makeConnector(null).onLifecycleEvent(() => {}, WC_CONTEXT)
+    ).toBeUndefined()
+  })
+
+  it('maps session_delete / session_expire / session_event for the ACTIVE topic and drops the address', () => {
+    const client = mockSignClient()
+    const events: WalletLifecycleEvent[] = []
+    const connector = makeConnector(client)
+    setActiveTopic(connector, 't-active')
+    const stop = connector.onLifecycleEvent(e => events.push(e), WC_CONTEXT)
+    expect(typeof stop).toBe('function')
+
+    client.fire('session_delete', { id: 1, topic: 't-active' })
+    client.fire('session_expire', { topic: 't-active' })
+    // CAIP session_event: accountsChanged carries an address we must NOT forward.
+    client.fire('session_event', {
+      id: 2,
+      topic: 't-active',
+      params: {
+        event: { name: 'accountsChanged', data: ['eip155:1:0xDEADBEEF'] },
+        chainId: 'eip155:1'
+      }
+    })
+    // Real WC payload shape: the NEW chain rides in `event.data` (EIP-1193
+    // convention); `params.chainId` is only the scope — here the PRE-switch
+    // chain, which must NOT be reported.
+    client.fire('session_event', {
+      id: 3,
+      topic: 't-active',
+      params: {
+        event: { name: 'chainChanged', data: '0x2105' },
+        chainId: 'eip155:1'
+      }
+    })
+
+    expect(events).toEqual([
+      { type: 'disconnect' },
+      { type: 'sessionExpired' },
+      { type: 'accountChanged' },
+      { type: 'chainChanged', chainId: 'eip155:8453' }
+    ])
+    expect(JSON.stringify(events)).not.toContain('0xDEADBEEF')
+
+    stop!()
+    expect(client.off).toHaveBeenCalledTimes(3)
+  })
+
+  it('drops lifecycle events from a NON-active topic (stale persisted session)', () => {
+    // A stale session left in WC storage from a previous pairing expiring must
+    // not surface as a phantom disconnect/expiry of the live session.
+    const client = mockSignClient()
+    const events: WalletLifecycleEvent[] = []
+    const connector = makeConnector(client)
+    setActiveTopic(connector, 't-active')
+    connector.onLifecycleEvent(e => events.push(e), WC_CONTEXT)
+
+    client.fire('session_delete', { id: 1, topic: 't-stale' })
+    client.fire('session_expire', { topic: 't-stale' })
+    client.fire('session_event', {
+      id: 2,
+      topic: 't-stale',
+      params: { event: { name: 'chainChanged' }, chainId: 'eip155:10' }
+    })
+
+    expect(events).toEqual([])
+  })
+
+  it('drops all lifecycle events when no session is active', () => {
+    // Post-disconnect (session cleared) the client can still emit for stored
+    // sessions; with no active topic nothing may be forwarded.
+    const client = mockSignClient()
+    const events: WalletLifecycleEvent[] = []
+    makeConnector(client).onLifecycleEvent(e => events.push(e), WC_CONTEXT)
+
+    client.fire('session_delete', { id: 1, topic: 't-any' })
+    client.fire('session_expire', { topic: 't-any' })
+
+    expect(events).toEqual([])
+  })
+
+  it('reads the active topic per event, so a re-connect is honoured live', () => {
+    const client = mockSignClient()
+    const events: WalletLifecycleEvent[] = []
+    const connector = makeConnector(client)
+    setActiveTopic(connector, 't-1')
+    connector.onLifecycleEvent(e => events.push(e), WC_CONTEXT)
+
+    client.fire('session_expire', { topic: 't-2' })
+    expect(events).toEqual([])
+
+    // New session replaces the old one (restore / re-connect) — events for the
+    // new topic must flow without re-subscribing.
+    setActiveTopic(connector, 't-2')
+    client.fire('session_expire', { topic: 't-2' })
+    expect(events).toEqual([{ type: 'sessionExpired' }])
+  })
+
+  it('normalizes chainChanged event.data variants to CAIP-2 and never falls back to the scope chain', () => {
+    const client = mockSignClient()
+    const events: WalletLifecycleEvent[] = []
+    const connector = makeConnector(client)
+    setActiveTopic(connector, 't-active')
+    connector.onLifecycleEvent(e => events.push(e), WC_CONTEXT)
+
+    const fire = (data: unknown) =>
+      client.fire('session_event', {
+        id: 1,
+        topic: 't-active',
+        params: { event: { name: 'chainChanged', data }, chainId: 'eip155:1' }
+      })
+
+    fire('0x89') // hex string
+    fire('137') // decimal string
+    fire(8453) // number
+    fire('eip155:10') // already CAIP-2
+    fire('eip155:0x2105') // CAIP-2 shape, but eip155 refs must be decimal
+    fire('tvm:-239') // non-eip155 namespace: reference is opaque, verbatim
+    // Malformed / missing / precision-lost data must yield a content-free
+    // event, NOT the scope chain (`eip155:1` here is the PRE-switch chain).
+    fire('0x1junk')
+    fire('eip155:junk') // CAIP-2 shape, eip155 ref neither decimal nor hex
+    fire(undefined)
+    fire('0x20000000000001') // 2^53+1: parseInt lost precision
+    // CAIP-2 shape boundaries — lock the validator's exact contract:
+    fire(`solana:${'a'.repeat(32)}`) // reference at the 32-char cap: valid
+    fire('ab:1') // namespace under 3 chars
+    fire('abcdefghi:1') // namespace over 8 chars
+    fire(`solana:${'a'.repeat(33)}`) // reference over the 32-char cap
+    fire('EIP155:1') // namespace must be lowercase
+    fire('tvm:-239:extra') // a second colon is not a CAIP-2 reference
+
+    expect(events).toEqual([
+      { type: 'chainChanged', chainId: 'eip155:137' },
+      { type: 'chainChanged', chainId: 'eip155:137' },
+      { type: 'chainChanged', chainId: 'eip155:8453' },
+      { type: 'chainChanged', chainId: 'eip155:10' },
+      { type: 'chainChanged', chainId: 'eip155:8453' },
+      { type: 'chainChanged', chainId: 'tvm:-239' },
+      { type: 'chainChanged' },
+      { type: 'chainChanged' },
+      { type: 'chainChanged' },
+      { type: 'chainChanged' },
+      { type: 'chainChanged', chainId: `solana:${'a'.repeat(32)}` },
+      { type: 'chainChanged' },
+      { type: 'chainChanged' },
+      { type: 'chainChanged' },
+      { type: 'chainChanged' },
+      { type: 'chainChanged' }
+    ])
+  })
+})

package/src/wallet-connect-connector.ts

@@ -1,5 +1,6 @@
 import type {
   Network,
+  NetworkId,
   Connector,
   ConnectorResult,
   SwitchNetworkResult,
@@ -9,7 +10,9 @@ import type {
   TransactionResult,
   NetworkRpcMap,
   SignatureType,
-  EIP712TypedData
+  EIP712TypedData,
+  WalletLifecycleEvent,
+  WalletLifecycleContext
 } from '@meshconnect/uwc-types'
 import { WalletConnectClient } from './services/walletconnect-client'
 import { ConnectionService } from './services/connection-service'
@@ -17,6 +20,101 @@ import { NetworkSwitchService } from './services/network-switch-service'
 import { SignatureService } from './services/signature-service'
 import { TransactionService } from './services/transaction-service'
 
+// The shape checks below are plain char loops, not regexes: the payload is
+// wallet-supplied, and the SAST gate fails the pipeline for ANY regex over
+// untrusted input (WS-I002-JAVASCRIPT-00082), linear-time or not.
+
+/** Non-empty and every char is a decimal digit. */
+function isDecimalString(value: string): boolean {
+  if (value.length === 0) return false
+  for (let i = 0; i < value.length; i++) {
+    const c = value.charCodeAt(i)
+    if (c < 48 || c > 57) return false
+  }
+  return true
+}
+
+/** `0x` followed by at least one hex digit, nothing else. */
+function isHexQuantity(value: string): boolean {
+  if (value.length < 3 || !value.startsWith('0x')) return false
+  for (let i = 2; i < value.length; i++) {
+    const c = value.charCodeAt(i)
+    const hex =
+      (c >= 48 && c <= 57) || (c >= 97 && c <= 102) || (c >= 65 && c <= 70)
+    if (!hex) return false
+  }
+  return true
+}
+
+/**
+ * CAIP-2 shape: `[a-z0-9]{3,8}` namespace, one colon, `[-_a-zA-Z0-9]{1,32}`
+ * reference. The reference charset excludes `:`, so a second colon fails.
+ */
+function isCaip2ChainId(value: string): boolean {
+  const colon = value.indexOf(':')
+  if (colon < 3 || colon > 8) return false
+  const referenceLength = value.length - colon - 1
+  if (referenceLength < 1 || referenceLength > 32) return false
+  for (let i = 0; i < colon; i++) {
+    const c = value.charCodeAt(i)
+    if (!((c >= 48 && c <= 57) || (c >= 97 && c <= 122))) return false
+  }
+  for (let i = colon + 1; i < value.length; i++) {
+    const c = value.charCodeAt(i)
+    const ok =
+      (c >= 48 && c <= 57) ||
+      (c >= 97 && c <= 122) ||
+      (c >= 65 && c <= 90) ||
+      c === 45 || // '-'
+      c === 95 // '_'
+    if (!ok) return false
+  }
+  return true
+}
+
+/**
+ * Normalize a WC `session_event` chainChanged payload to CAIP-2. The NEW chain
+ * travels in `event.data` (hex / decimal string / number per the EIP-1193
+ * convention — WalletConnect's own EthereumProvider reads `event.data`); the
+ * sibling `params.chainId` is only the CAIP-2 scope the event was emitted
+ * under, i.e. potentially the PRE-switch chain, so it donates its namespace
+ * and nothing else. Unparseable data yields undefined — a content-free
+ * `chainChanged` beats a wrong chain id.
+ */
+function toCaipChainId(data: unknown, scope: unknown): NetworkId | undefined {
+  if (typeof data === 'string' && isCaip2ChainId(data)) {
+    // Some wallets already send CAIP-2. An eip155 reference must be DECIMAL
+    // per CAIP-2, so a non-decimal ref (`eip155:0x1`) re-enters the numeric
+    // normalization below — the namespace survives via the `scope` argument.
+    // The shape check guarantees one colon with a non-empty tail; the
+    // fallback only satisfies noUncheckedIndexedAccess.
+    const [namespace, reference = ''] = data.split(':')
+    if (namespace !== 'eip155' || isDecimalString(reference)) {
+      return data as NetworkId
+    }
+    return toCaipChainId(reference, data)
+  }
+  let decimal: number | undefined
+  if (typeof data === 'string') {
+    // Full-shape match before converting: parseInt('0x1junk', 16) === 1.
+    if (isHexQuantity(data)) {
+      decimal = parseInt(data, 16)
+    } else if (isDecimalString(data)) {
+      decimal = parseInt(data, 10)
+    }
+  } else if (typeof data === 'number' && Number.isInteger(data) && data >= 0) {
+    decimal = data
+  }
+  // isSafeInteger: beyond 2^53-1 parseInt has already lost precision —
+  // emitting a silently-wrong chain id is worse than emitting none.
+  if (decimal === undefined || !Number.isSafeInteger(decimal)) return undefined
+  const namespace =
+    typeof scope === 'string' && scope.includes(':')
+      ? scope.split(':')[0]
+      : 'eip155'
+  return `${namespace}:${decimal}` as NetworkId
+}
+
 export class WalletConnectConnector implements Connector {
   private walletConnectClient: WalletConnectClient
   private connectionService: ConnectionService
@@ -25,8 +123,12 @@ export class WalletConnectConnector implements Connector {
   private transactionService: TransactionService
   private networkRpcMap: NetworkRpcMap
 
-  constructor(config: WalletConnectConfig, networkRpcMap: NetworkRpcMap = {}) {
-    this.walletConnectClient = new WalletConnectClient(config)
+  constructor(
+    config: WalletConnectConfig,
+    networkRpcMap: NetworkRpcMap = {},
+    onRelayError?: (error: unknown) => void
+  ) {
+    this.walletConnectClient = new WalletConnectClient(config, onRelayError)
     this.networkRpcMap = networkRpcMap
     this.connectionService = new ConnectionService(this.walletConnectClient)
     this.networkSwitchService = new NetworkSwitchService(
@@ -99,4 +201,75 @@ export class WalletConnectConnector implements Connector {
   ): Promise<Uint8Array> {
     return this.transactionService.signSolanaTransactionBytes(serializedTx)
   }
+
+  /**
+   * Observe post-connect lifecycle from the WalletConnect SignClient. Unlike the
+   * injected path, the SignClient lives IN this context (its own relay, not the
+   * iframe bridge), so this works in the production iframe too — no bridge needed.
+   *
+   * Maps the verified SignClient events (`@walletconnect/types`): `session_delete`
+   * → disconnect, `session_expire` → sessionExpired, and `session_event` (CAIP
+   * `accountsChanged` / `chainChanged`, the latter normalized to CAIP-2 from
+   * `event.data` — see `toCaipChainId`). The account address in the event
+   * payload is never forwarded. Returns undefined before a session exists so
+   * the core reports lifecycle unavailable.
+   *
+   * TOPIC FILTER: SignClient events are client-global and WC v2 persists old
+   * sessions in storage, so a stale session expiring would otherwise surface as a
+   * phantom disconnect/expiry of the live one. Every payload carries a `topic`
+   * (`@walletconnect/types` BaseEventArgs); only the ACTIVE session's topic is
+   * forwarded, resolved per event so a restore/re-connect is honoured live.
+   */
+  onLifecycleEvent(
+    listener: (event: WalletLifecycleEvent) => void,
+    // The active-session TOPIC (below) is the discriminator here — the context
+    // names the session but carries no topic, so it is accepted for contract
+    // parity and unused.
+    _context: WalletLifecycleContext
+  ): (() => void) | undefined {
+    const client = this.walletConnectClient.getExistingClient()
+    if (!client) return undefined
+
+    const isActiveTopic = (topic: string | undefined): boolean => {
+      const active = this.connectionService.getSession()?.topic
+      return active !== undefined && topic === active
+    }
+
+    const onDelete = (args: { topic: string }) => {
+      if (isActiveTopic(args?.topic)) listener({ type: 'disconnect' })
+    }
+    const onExpire = (args: { topic: string }) => {
+      if (isActiveTopic(args?.topic)) listener({ type: 'sessionExpired' })
+    }
+    const onSessionEvent = (args: {
+      topic: string
+      params: { event: { name: string; data?: unknown }; chainId: string }
+    }) => {
+      if (!isActiveTopic(args?.topic)) return
+      const name = args?.params?.event?.name
+      if (name === 'accountsChanged') {
+        // Address dropped — signal THAT it changed, not which.
+        listener({ type: 'accountChanged' })
+      } else if (name === 'chainChanged') {
+        // The new chain is in `event.data`; `params.chainId` is only the scope.
+        const chainId = toCaipChainId(
+          args?.params?.event?.data,
+          args?.params?.chainId
+        )
+        listener(
+          chainId ? { type: 'chainChanged', chainId } : { type: 'chainChanged' }
+        )
+      }
+    }
+
+    client.on('session_delete', onDelete)
+    client.on('session_expire', onExpire)
+    client.on('session_event', onSessionEvent)
+
+    return () => {
+      client.off('session_delete', onDelete)
+      client.off('session_expire', onExpire)
+      client.off('session_event', onSessionEvent)
+    }
+  }
 }