@meshconnect/uwc-types 0.19.0 → 0.20.0-snapshot.103d25f

package/dist/connector.d.ts

@@ -44,6 +44,12 @@ export interface ConnectorResult {
     address: string;
     availableAddresses: AvailableAddress[];
     publicKey?: string;
+    /**
+     * True when the connector satisfied this connect() by adopting a live stored
+     * session instead of a fresh pairing (WalletConnect session reuse, MFS-642).
+     * Propagated onto the Session for observability. Absent = fresh connect.
+     */
+    reused?: boolean;
 }
 /**
  * Result interface for network switch operations
@@ -53,6 +59,21 @@ export interface SwitchNetworkResult {
     address: string;
     availableAddresses?: AvailableAddress[];
 }
+/**
+ * Optional per-call hints for connect(). Additive and connector-agnostic —
+ * connectors that do not use a field simply ignore it.
+ */
+export interface ConnectOptions {
+    /**
+     * Display name of the wallet the user selected (from the catalog). The
+     * WalletConnect connector keys its session-reuse record on this trusted name:
+     * it only ever re-adopts a session it previously recorded for the same selected
+     * wallet, never one established by another (possibly rogue) peer. Ignored by
+     * connectors without session reuse; absence disables reuse (fresh pairing is
+     * always safe).
+     */
+    walletName?: string;
+}
 /**
  * Common interface for all wallet connectors
  */
@@ -63,7 +84,7 @@ export interface Connector {
      * @param args Additional arguments specific to the connector type
      * @returns A promise that resolves to a ConnectorResult containing the network ID, wallet address, and available addresses
      */
-    connect(network: Network, provider?: ExtensionInjectedProvider | IntegratedBrowserInjectedProvider | WalletConnectProvider | TonConnectWalletProvider): Promise<ConnectorResult>;
+    connect(network: Network, provider?: ExtensionInjectedProvider | IntegratedBrowserInjectedProvider | WalletConnectProvider | TonConnectWalletProvider, options?: ConnectOptions): Promise<ConnectorResult>;
     /**
      * Get the connection URI for the wallet, if applicable
      * This is typically used for WalletConnect or similar protocols
@@ -73,6 +94,18 @@ export interface Connector {
      * @remarks This method is optional and may not be implemented by all connectors.
      */
     getConnectionURI?(): string;
+    /**
+     * Pre-generate a connection pairing (URI) ahead of wallet selection, WITHOUT
+     * waiting for approval. Warms the transport (e.g. opens the WalletConnect relay
+     * socket on a cold client) and returns a URI the caller can deep-link inside a
+     * user gesture; a subsequent `connect()` adopts the same pairing so the URI the
+     * user approves matches the one opened. Optional — only connectors with a
+     * pairing step (WalletConnect) implement it.
+     * @param provider Only `supportedNetworkIds` is required (pass the UNION of the
+     *   session's WalletConnect wallets' networks so one pairing serves any wallet).
+     * @returns The pairing URI.
+     */
+    beginPairing?(provider: Pick<WalletConnectProvider, 'supportedNetworkIds'>): Promise<string>;
     /**
      * Disconnect from the wallet
      * This method is optional and may not be implemented by all connectors.

package/dist/connector.d.ts.map

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

package/dist/observability.d.ts

@@ -11,6 +11,67 @@
  * wires them to whatever backend they run (Datadog, Amplitude, Segment, …).
  */
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Why an opt-in WalletConnect session-reuse attempt fell back to a fresh pairing
+ * instead of adopting a stored session (MFS-642). Small, stable enum so it can
+ * drive a reuse-outcome dashboard without high cardinality. Emitted via
+ * `WalletConnectConfig.onSessionReuseSkipped`.
+ *
+ * - `unscoped`    — reuse is on but no `sessionReuseScopeId` was supplied (e.g. the
+ *                   link token carries no end-user id), so reuse is disabled by
+ *                   the user-binding rule. Split from `no_record` so the funnel
+ *                   separates "first connect" from "this consumer/user can never
+ *                   reuse" — the latter sizes the traffic where the integration
+ *                   (not the user) blocks adoption.
+ * - `no_record`   — no topic recorded for the selected wallet (e.g. first connect),
+ *                   or the recorded session is no longer in storage.
+ * - `expired`     — the recorded session exists but is past its expiry, or expires
+ *                   too soon to survive the signing flow (min-remaining-TTL guard).
+ * - `no_address`  — the session carries no account for the requested network.
+ * - `ping_timeout`— the liveness ping got NO ack within the bounded window (peer
+ *                   slow/suspended or the relay socket is dead — CARE-263). Split
+ *                   from `ping_error` so a slow-but-alive mobile wallet (which
+ *                   would defeat reuse if the window is too tight) is measurable
+ *                   separately from a hard failure.
+ * - `ping_error`  — the ping REJECTED (offline / relay / protocol error), i.e. an
+ *                   unknown liveness state rather than a confirmed no-ack.
+ * - `superseded`  — a disconnect()/newer connect() invalidated the attempt mid-ping.
+ */
+export type WalletConnectSessionReuseSkipReason = 'unscoped' | 'no_record' | 'expired' | 'no_address' | 'ping_timeout' | 'ping_error' | 'superseded';
+/**
+ * Payload for `WalletConnectConfig.onSessionReuseSkipped`. Carries the coarse
+ * reason plus, for the two ping outcomes, the ping round-trip in ms — so a
+ * consumer can chart the ping-latency distribution and decide whether the bound
+ * is clipping live-but-slow wallets. (The healthy-ping latency is separately
+ * observable as the reused connect's own handoff duration.)
+ */
+export interface WalletConnectSessionReuseSkip {
+    reason: WalletConnectSessionReuseSkipReason;
+    /** Ping round-trip in ms; present only for `ping_timeout` / `ping_error`. */
+    pingMs?: number;
+}
+/**
+ * Payload for `WalletConnectConfig.onSessionRestored` — context about the
+ * adopted session, for triaging reused-session failures per wallet (e.g. "does
+ * wallet X only fail when the session is close to expiry / was adopted stale?").
+ * Telemetry-only; adoption itself is decided before this fires.
+ */
+export interface WalletConnectSessionRestored {
+    /**
+     * Seconds until the adopted session's WC expiry. WC v2 extends expiry on
+     * activity, so LOW values mean the session sat unused — the stale-session
+     * facet to correlate with a subsequent sign timeout on the same session.
+     */
+    expiresInSeconds: number;
+    /**
+     * The peer's self-reported wallet name (`session.peer.metadata.name`).
+     * UNAUTHENTICATED — never a trust input (adoption is keyed by the app-recorded
+     * topic, see the connector's reuse trust anchor); carried only so telemetry can
+     * facet reused-session outcomes by what the wallet claims to be, e.g. to isolate
+     * a wallet-specific reuse quirk (Rainbow, CARE-263).
+     */
+    peerName?: string;
+}
 /**
  * Pluggable logger. The default implementation (`createLogger`) is console-backed
  * and level-gated; inject your own to redirect UWC's internal logging into your

package/dist/observability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GACtB,wBAAwB,GACxB,+BAA+B,GAC/B,wBAAwB,GACxB,qBAAqB,GACrB,cAAc,GACd,qBAAqB,GACrB,4BAA4B,GAC5B,wBAAwB,GACxB,SAAS,CAAA;AAEb;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;AAEnE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,eAAe;AACjB,iFAAiF;GAC/E,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,SAAS;AACX,gFAAgF;GAC9E,oBAAoB,GACpB,SAAS,CAAA;AAEb;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,UAAU,GACV,WAAW,GACX,QAAQ,GACR,KAAK,GACL,SAAS,CAAA;AAEb;;;;GAIG;AACH,MAAM,MAAM,0BAA0B;AACpC,gGAAgG;AAC9F,mCAAmC;AACrC,uFAAuF;GACrF,iCAAiC;AACnC,oEAAoE;GAClE,uBAAuB;AACzB;;;;GAIG;GACD,mBAAmB;AACrB;;;GAGG;GACD,cAAc,CAAA"}
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,mCAAmC,GAC3C,UAAU,GACV,WAAW,GACX,SAAS,GACT,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,YAAY,CAAA;AAEhB;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,mCAAmC,CAAA;IAC3C,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GACtB,wBAAwB,GACxB,+BAA+B,GAC/B,wBAAwB,GACxB,qBAAqB,GACrB,cAAc,GACd,qBAAqB,GACrB,4BAA4B,GAC5B,wBAAwB,GACxB,SAAS,CAAA;AAEb;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;AAEnE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,eAAe;AACjB,iFAAiF;GAC/E,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,SAAS;AACX,gFAAgF;GAC9E,oBAAoB,GACpB,SAAS,CAAA;AAEb;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,UAAU,GACV,WAAW,GACX,QAAQ,GACR,KAAK,GACL,SAAS,CAAA;AAEb;;;;GAIG;AACH,MAAM,MAAM,0BAA0B;AACpC,gGAAgG;AAC9F,mCAAmC;AACrC,uFAAuF;GACrF,iCAAiC;AACnC,oEAAoE;GAClE,uBAAuB;AACzB;;;;GAIG;GACD,mBAAmB;AACrB;;;GAGG;GACD,cAAc,CAAA"}

package/dist/session.d.ts

@@ -16,5 +16,14 @@ export interface Session {
     availableNetworks: Network[];
     activeWallet: WalletMetadata | null;
     availableAddresses: AvailableAddress[];
+    /**
+     * Connection provenance: true when this session was adopted from a live stored
+     * WalletConnect session (MFS-642 reuse) rather than established by a fresh
+     * pairing handshake. Drives observability — it rides the `connected` telemetry
+     * and every subsequent operation handoff so success/error/timeout of reused
+     * sessions can be evaluated and triaged separately from fresh ones. Absent/false
+     * for fresh pairings and all non-WalletConnect connections.
+     */
+    reused?: boolean;
 }
 //# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,cAAc,EAAE,cAAc,GAAG,IAAI,CAAA;IACrC,aAAa,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7B,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,IAAI,CAAA;IAChE,+BAA+B,EAAE,eAAe,GAAG,IAAI,CAAA;IACvD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,iBAAiB,EAAE,OAAO,EAAE,CAAA;IAC5B,YAAY,EAAE,cAAc,GAAG,IAAI,CAAA;IACnC,kBAAkB,EAAE,gBAAgB,EAAE,CAAA;CACvC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,cAAc,EAAE,cAAc,GAAG,IAAI,CAAA;IACrC,aAAa,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7B,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,IAAI,CAAA;IAChE,+BAA+B,EAAE,eAAe,GAAG,IAAI,CAAA;IACvD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,iBAAiB,EAAE,OAAO,EAAE,CAAA;IAC5B,YAAY,EAAE,cAAc,GAAG,IAAI,CAAA;IACnC,kBAAkB,EAAE,gBAAgB,EAAE,CAAA;IACtC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB"}

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

@@ -1,3 +1,4 @@
+import type { WalletConnectSessionRestored, WalletConnectSessionReuseSkip } from './observability';
 /**
  * Configuration for WalletConnect connector
  */
@@ -9,5 +10,65 @@ export interface WalletConnectConfig {
         url: string;
         icons: string[];
     };
+    /**
+     * Opt-in: reuse a live WalletConnect session persisted in storage instead of
+     * forcing a fresh pairing approval on every connect(). WC v2 keeps approved
+     * sessions in the SignClient's storage (IndexedDB) for their full ~7-day TTL;
+     * with this off (the default) UWC ignores them and always re-pairs — the
+     * historical behaviour (MFS-642). When on, connect() first looks for a stored
+     * session whose namespaces cover the requested network and reuses it, skipping
+     * the QR/deep-link round-trip; it falls back to a fresh pairing when none is
+     * usable. Default false so existing consumers are byte-for-byte unaffected and
+     * the blast radius is opt-in per consumer.
+     *
+     * The SignClient (and its storage) lives in the SAME context that runs this
+     * connector — for Mesh Link that is the web.meshconnect.com iframe, whose
+     * per-origin IndexedDB survives the iframe being torn down and re-created — so
+     * reuse works in the production iframe without any bridge round-trip.
+     */
+    enableSessionReuse?: boolean;
+    /**
+     * Fired once when connect() resolves from a reused stored session instead of a
+     * fresh pairing handshake, with context about the adopted session — time to WC
+     * expiry and the peer's (unauthenticated) self-reported name — so reused-session
+     * failures can be triaged per wallet and correlated with session staleness.
+     * Optional — omitting it keeps reuse working, only the signal is dropped.
+     * No-op unless enableSessionReuse is on. Mirrors TonConnectConfig.onSessionRestored.
+     */
+    onSessionRestored?: (restored: WalletConnectSessionRestored) => void;
+    /**
+     * Fired when reuse was attempted (enableSessionReuse on + wallet known) but fell
+     * back to a fresh pairing. Carries the coarse `reason` plus, for the ping
+     * outcomes, the ping round-trip (`pingMs`). The counterpart to onSessionRestored:
+     * together they give a reuse-outcome funnel (reused vs the reason it wasn't) for
+     * monitoring. Telemetry-only; never affects behaviour. No-op unless
+     * enableSessionReuse is on.
+     */
+    onSessionReuseSkipped?: (skip: WalletConnectSessionReuseSkip) => void;
+    /**
+     * SECURITY-CRITICAL user binding for session reuse. The Mesh Link iframe shares
+     * one origin across every client and end-user, so a stored session must be
+     * bound to the authenticated Link user — otherwise a later user on the same
+     * device could silently adopt an earlier user's live session without a fresh
+     * approval. Pass a stable per-user id (the Link user id). Reuse is DISABLED when
+     * this is empty/absent, regardless of `enableSessionReuse` (skips report as
+     * `unscoped`) — origin persistence alone is never sufficient. The id is hashed
+     * before it is persisted, so a PII-bearing id (merchants sometimes use emails as
+     * user ids) never lands in storage verbatim. No-op unless enableSessionReuse is on.
+     */
+    sessionReuseScopeId?: string;
+    /**
+     * Opt-in liveness-ping window (ms) for session reuse. Reuse is OPTIMISTIC by
+     * default: when this is unset (or ≤ 0) connect() adopts a stored session with no
+     * blocking probe — matching WC's own restore and every mainstream dApp connector
+     * — and a dead peer surfaces at the first sign (bounded by the app's signing
+     * escape hatch), not by making every relaunch wait. Set a positive number only if
+     * you would rather pay an up-front ping and re-pair immediately than risk a late
+     * failure; a too-tight bound will discard live-but-slow mobile peers (they often
+     * need > 4s to ack over the relay), so calibrate against the `pingMs` carried by
+     * onSessionReuseSkipped. Exposed as config so this bound can be tuned per consumer
+     * without a new UWC release. No-op unless enableSessionReuse is on.
+     */
+    sessionReusePingTimeoutMs?: number;
 }
 //# 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;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE;QACT,IAAI,EAAE,MAAM,CAAA;QACZ,WAAW,EAAE,MAAM,CAAA;QACnB,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,EAAE,CAAA;KAChB,CAAA;CACF"}
+{"version":3,"file":"wallet-connect-connector.d.ts","sourceRoot":"","sources":["../src/wallet-connect-connector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAC5B,6BAA6B,EAC9B,MAAM,iBAAiB,CAAA;AAExB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE;QACT,IAAI,EAAE,MAAM,CAAA;QACZ,WAAW,EAAE,MAAM,CAAA;QACnB,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,EAAE,CAAA;KAChB,CAAA;IACD;;;;;;;;;;;;;;;OAeG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,4BAA4B,KAAK,IAAI,CAAA;IACpE;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE,6BAA6B,KAAK,IAAI,CAAA;IACrE;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAA;CACnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshconnect/uwc-types",
-  "version": "0.19.0",
+  "version": "0.20.0-snapshot.103d25f",
   "description": "TypeScript types for Universal Wallet Connector",
   "type": "module",
   "main": "dist/index.js",

package/src/connector.ts

@@ -56,6 +56,12 @@ export interface ConnectorResult {
   address: string
   availableAddresses: AvailableAddress[]
   publicKey?: string
+  /**
+   * True when the connector satisfied this connect() by adopting a live stored
+   * session instead of a fresh pairing (WalletConnect session reuse, MFS-642).
+   * Propagated onto the Session for observability. Absent = fresh connect.
+   */
+  reused?: boolean
 }
 
 /**
@@ -67,6 +73,22 @@ export interface SwitchNetworkResult {
   availableAddresses?: AvailableAddress[]
 }
 
+/**
+ * Optional per-call hints for connect(). Additive and connector-agnostic —
+ * connectors that do not use a field simply ignore it.
+ */
+export interface ConnectOptions {
+  /**
+   * Display name of the wallet the user selected (from the catalog). The
+   * WalletConnect connector keys its session-reuse record on this trusted name:
+   * it only ever re-adopts a session it previously recorded for the same selected
+   * wallet, never one established by another (possibly rogue) peer. Ignored by
+   * connectors without session reuse; absence disables reuse (fresh pairing is
+   * always safe).
+   */
+  walletName?: string
+}
+
 /**
  * Common interface for all wallet connectors
  */
@@ -84,7 +106,8 @@ export interface Connector {
       | ExtensionInjectedProvider
       | IntegratedBrowserInjectedProvider
       | WalletConnectProvider
-      | TonConnectWalletProvider
+      | TonConnectWalletProvider,
+    options?: ConnectOptions
   ): Promise<ConnectorResult>
 
   /**
@@ -97,6 +120,21 @@ export interface Connector {
    */
   getConnectionURI?(): string
 
+  /**
+   * Pre-generate a connection pairing (URI) ahead of wallet selection, WITHOUT
+   * waiting for approval. Warms the transport (e.g. opens the WalletConnect relay
+   * socket on a cold client) and returns a URI the caller can deep-link inside a
+   * user gesture; a subsequent `connect()` adopts the same pairing so the URI the
+   * user approves matches the one opened. Optional — only connectors with a
+   * pairing step (WalletConnect) implement it.
+   * @param provider Only `supportedNetworkIds` is required (pass the UNION of the
+   *   session's WalletConnect wallets' networks so one pairing serves any wallet).
+   * @returns The pairing URI.
+   */
+  beginPairing?(
+    provider: Pick<WalletConnectProvider, 'supportedNetworkIds'>
+  ): Promise<string>
+
   /**
    * Disconnect from the wallet
    * This method is optional and may not be implemented by all connectors.

package/src/observability.ts

@@ -13,6 +13,77 @@
 
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
 
+/**
+ * Why an opt-in WalletConnect session-reuse attempt fell back to a fresh pairing
+ * instead of adopting a stored session (MFS-642). Small, stable enum so it can
+ * drive a reuse-outcome dashboard without high cardinality. Emitted via
+ * `WalletConnectConfig.onSessionReuseSkipped`.
+ *
+ * - `unscoped`    — reuse is on but no `sessionReuseScopeId` was supplied (e.g. the
+ *                   link token carries no end-user id), so reuse is disabled by
+ *                   the user-binding rule. Split from `no_record` so the funnel
+ *                   separates "first connect" from "this consumer/user can never
+ *                   reuse" — the latter sizes the traffic where the integration
+ *                   (not the user) blocks adoption.
+ * - `no_record`   — no topic recorded for the selected wallet (e.g. first connect),
+ *                   or the recorded session is no longer in storage.
+ * - `expired`     — the recorded session exists but is past its expiry, or expires
+ *                   too soon to survive the signing flow (min-remaining-TTL guard).
+ * - `no_address`  — the session carries no account for the requested network.
+ * - `ping_timeout`— the liveness ping got NO ack within the bounded window (peer
+ *                   slow/suspended or the relay socket is dead — CARE-263). Split
+ *                   from `ping_error` so a slow-but-alive mobile wallet (which
+ *                   would defeat reuse if the window is too tight) is measurable
+ *                   separately from a hard failure.
+ * - `ping_error`  — the ping REJECTED (offline / relay / protocol error), i.e. an
+ *                   unknown liveness state rather than a confirmed no-ack.
+ * - `superseded`  — a disconnect()/newer connect() invalidated the attempt mid-ping.
+ */
+export type WalletConnectSessionReuseSkipReason =
+  | 'unscoped'
+  | 'no_record'
+  | 'expired'
+  | 'no_address'
+  | 'ping_timeout'
+  | 'ping_error'
+  | 'superseded'
+
+/**
+ * Payload for `WalletConnectConfig.onSessionReuseSkipped`. Carries the coarse
+ * reason plus, for the two ping outcomes, the ping round-trip in ms — so a
+ * consumer can chart the ping-latency distribution and decide whether the bound
+ * is clipping live-but-slow wallets. (The healthy-ping latency is separately
+ * observable as the reused connect's own handoff duration.)
+ */
+export interface WalletConnectSessionReuseSkip {
+  reason: WalletConnectSessionReuseSkipReason
+  /** Ping round-trip in ms; present only for `ping_timeout` / `ping_error`. */
+  pingMs?: number
+}
+
+/**
+ * Payload for `WalletConnectConfig.onSessionRestored` — context about the
+ * adopted session, for triaging reused-session failures per wallet (e.g. "does
+ * wallet X only fail when the session is close to expiry / was adopted stale?").
+ * Telemetry-only; adoption itself is decided before this fires.
+ */
+export interface WalletConnectSessionRestored {
+  /**
+   * Seconds until the adopted session's WC expiry. WC v2 extends expiry on
+   * activity, so LOW values mean the session sat unused — the stale-session
+   * facet to correlate with a subsequent sign timeout on the same session.
+   */
+  expiresInSeconds: number
+  /**
+   * The peer's self-reported wallet name (`session.peer.metadata.name`).
+   * UNAUTHENTICATED — never a trust input (adoption is keyed by the app-recorded
+   * topic, see the connector's reuse trust anchor); carried only so telemetry can
+   * facet reused-session outcomes by what the wallet claims to be, e.g. to isolate
+   * a wallet-specific reuse quirk (Rainbow, CARE-263).
+   */
+  peerName?: string
+}
+
 /**
  * Pluggable logger. The default implementation (`createLogger`) is console-backed
  * and level-gated; inject your own to redirect UWC's internal logging into your

package/src/session.ts

@@ -18,4 +18,13 @@ export interface Session {
   availableNetworks: Network[]
   activeWallet: WalletMetadata | null
   availableAddresses: AvailableAddress[]
+  /**
+   * Connection provenance: true when this session was adopted from a live stored
+   * WalletConnect session (MFS-642 reuse) rather than established by a fresh
+   * pairing handshake. Drives observability — it rides the `connected` telemetry
+   * and every subsequent operation handoff so success/error/timeout of reused
+   * sessions can be evaluated and triaged separately from fresh ones. Absent/false
+   * for fresh pairings and all non-WalletConnect connections.
+   */
+  reused?: boolean
 }

package/src/wallet-connect-connector.ts

@@ -1,3 +1,8 @@
+import type {
+  WalletConnectSessionRestored,
+  WalletConnectSessionReuseSkip
+} from './observability'
+
 /**
  * Configuration for WalletConnect connector
  */
@@ -9,4 +14,64 @@ export interface WalletConnectConfig {
     url: string
     icons: string[]
   }
+  /**
+   * Opt-in: reuse a live WalletConnect session persisted in storage instead of
+   * forcing a fresh pairing approval on every connect(). WC v2 keeps approved
+   * sessions in the SignClient's storage (IndexedDB) for their full ~7-day TTL;
+   * with this off (the default) UWC ignores them and always re-pairs — the
+   * historical behaviour (MFS-642). When on, connect() first looks for a stored
+   * session whose namespaces cover the requested network and reuses it, skipping
+   * the QR/deep-link round-trip; it falls back to a fresh pairing when none is
+   * usable. Default false so existing consumers are byte-for-byte unaffected and
+   * the blast radius is opt-in per consumer.
+   *
+   * The SignClient (and its storage) lives in the SAME context that runs this
+   * connector — for Mesh Link that is the web.meshconnect.com iframe, whose
+   * per-origin IndexedDB survives the iframe being torn down and re-created — so
+   * reuse works in the production iframe without any bridge round-trip.
+   */
+  enableSessionReuse?: boolean
+  /**
+   * Fired once when connect() resolves from a reused stored session instead of a
+   * fresh pairing handshake, with context about the adopted session — time to WC
+   * expiry and the peer's (unauthenticated) self-reported name — so reused-session
+   * failures can be triaged per wallet and correlated with session staleness.
+   * Optional — omitting it keeps reuse working, only the signal is dropped.
+   * No-op unless enableSessionReuse is on. Mirrors TonConnectConfig.onSessionRestored.
+   */
+  onSessionRestored?: (restored: WalletConnectSessionRestored) => void
+  /**
+   * Fired when reuse was attempted (enableSessionReuse on + wallet known) but fell
+   * back to a fresh pairing. Carries the coarse `reason` plus, for the ping
+   * outcomes, the ping round-trip (`pingMs`). The counterpart to onSessionRestored:
+   * together they give a reuse-outcome funnel (reused vs the reason it wasn't) for
+   * monitoring. Telemetry-only; never affects behaviour. No-op unless
+   * enableSessionReuse is on.
+   */
+  onSessionReuseSkipped?: (skip: WalletConnectSessionReuseSkip) => void
+  /**
+   * SECURITY-CRITICAL user binding for session reuse. The Mesh Link iframe shares
+   * one origin across every client and end-user, so a stored session must be
+   * bound to the authenticated Link user — otherwise a later user on the same
+   * device could silently adopt an earlier user's live session without a fresh
+   * approval. Pass a stable per-user id (the Link user id). Reuse is DISABLED when
+   * this is empty/absent, regardless of `enableSessionReuse` (skips report as
+   * `unscoped`) — origin persistence alone is never sufficient. The id is hashed
+   * before it is persisted, so a PII-bearing id (merchants sometimes use emails as
+   * user ids) never lands in storage verbatim. No-op unless enableSessionReuse is on.
+   */
+  sessionReuseScopeId?: string
+  /**
+   * Opt-in liveness-ping window (ms) for session reuse. Reuse is OPTIMISTIC by
+   * default: when this is unset (or ≤ 0) connect() adopts a stored session with no
+   * blocking probe — matching WC's own restore and every mainstream dApp connector
+   * — and a dead peer surfaces at the first sign (bounded by the app's signing
+   * escape hatch), not by making every relaunch wait. Set a positive number only if
+   * you would rather pay an up-front ping and re-pair immediately than risk a late
+   * failure; a too-tight bound will discard live-but-slow mobile peers (they often
+   * need > 4s to ack over the relay), so calibrate against the `pingMs` carried by
+   * onSessionReuseSkipped. Exposed as config so this bound can be tuned per consumer
+   * without a new UWC release. No-op unless enableSessionReuse is on.
+   */
+  sessionReusePingTimeoutMs?: number
 }