@rango-dev/provider-walletconnect-2 0.57.0 → 0.57.1-next.0

package/dist/session/teardown.d.ts

@@ -0,0 +1,24 @@
+import type { SignClientInstance, WalletConnectNamespace } from '../types.js';
+import type { ISignClient, SessionTypes } from '@walletconnect/types';
+import type UniversalProvider from '@walletconnect/universal-provider';
+export declare function hasActiveSession(client: ISignClient, topic: string): boolean;
+export declare function hasActivePairing(client: SignClientInstance, topic: string): boolean;
+export declare function expireWalletConnectTopic(client: SignClientInstance, topic: string): Promise<void>;
+export declare function removeSessionRecord(client: SignClientInstance, session: SessionTypes.Struct): Promise<void>;
+export declare function purgeOrphanedSessions(client: SignClientInstance): Promise<void>;
+/**
+ * Drops pairings that no session is using.
+ *
+ * The inverse of {@link purgeOrphanedSessions}, and the only thing that collects
+ * them: a cancelled connect leaves behind the pairing `client.connect()` minted,
+ * and `cleanupPendingPairings` only unsubscribes pairings - it never deletes the
+ * record. Without this they accumulate in `client.pairing` and in storage for the
+ * lifetime of the origin.
+ *
+ * Only safe to call while no connect is in flight (the adapter's `#sessionQueue`
+ * guarantees that): a pairing awaiting its first approval has no session yet, so
+ * dropping it would kill that handshake.
+ */
+export declare function purgeOrphanedPairings(client: SignClientInstance): Promise<void>;
+export declare function cleanupStaleSessionsForNamespace(client: UniversalProvider['client'], namespace: WalletConnectNamespace): Promise<void>;
+//# sourceMappingURL=teardown.d.ts.map

package/dist/session/teardown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"teardown.d.ts","sourceRoot":"","sources":["../../src/session/teardown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,KAAK,iBAAiB,MAAM,mCAAmC,CAAC;AAevE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAM5E;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,MAAM,GACZ,OAAO,CAET;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,MAAM,iBAkBd;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,YAAY,CAAC,MAAM,iBA8C7B;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EACnC,SAAS,EAAE,sBAAsB,GAChC,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/signer.d.ts

@@ -1,3 +1,3 @@
-import type { WCInstance } from './types.js';
 import type { SignerFactory } from 'rango-types';
-export default function getSigners(instance: WCInstance): Promise<SignerFactory>;
+export default function getSigners(): Promise<SignerFactory>;
+//# sourceMappingURL=signer.d.ts.map

package/dist/signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAOjD,wBAA8B,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC,CAoBjE"}

package/dist/signers/evm.d.ts

@@ -1,7 +1,7 @@
-import type { SignClient } from '@walletconnect/sign-client/dist/types/client';
-import type { SessionTypes } from '@walletconnect/types';
+import type { ISignClient, SessionTypes } from '@walletconnect/types';
 import type { EvmTransaction } from 'rango-types/mainApi';
 import { type GenericSigner } from 'rango-types';
+type SessionGetter = () => SessionTypes.Struct | null;
 type WalletConnectEvmTx = {
     from?: string;
     to?: string;
@@ -15,8 +15,9 @@ type WalletConnectEvmTx = {
 };
 declare class EVMSigner implements GenericSigner<EvmTransaction> {
     private client;
-    private session;
-    constructor(client: SignClient, session: SessionTypes.Struct);
+    private getSession;
+    constructor(client: ISignClient, getSession: SessionGetter);
+    private get session();
     /**
      * Map Rango's EvmTransaction to WalletConnect eth_sendTransaction params.
      *
@@ -36,3 +37,4 @@ declare class EVMSigner implements GenericSigner<EvmTransaction> {
     private isNetworkAndAccountExistInSession;
 }
 export default EVMSigner;
+//# sourceMappingURL=evm.d.ts.map

package/dist/signers/evm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.d.ts","sourceRoot":"","sources":["../../src/signers/evm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAOjD,KAAK,aAAa,GAAG,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,CAAC;AAEtD,KAAK,kBAAkB,GAAG;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,cAAM,SAAU,YAAW,aAAa,CAAC,cAAc,CAAC;IACtD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,UAAU,CAAgB;gBAEtB,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa;IAK1D,OAAO,KAAK,OAAO,GAMlB;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,kBAAkB;IAgC5C,WAAW,CACtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,MAAM,CAAC;IAqCZ,aAAa,CACjB,EAAE,EAAE,cAAc,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAuC5B,OAAO,CAAC,iCAAiC;CAgD1C;AAED,eAAe,SAAS,CAAC"}

package/dist/types.d.ts

@@ -1,21 +1,38 @@
-import type { SignClient } from '@walletconnect/sign-client/dist/types/client';
-import type { ProposalTypes, SessionTypes } from '@walletconnect/types';
+import type { ProposalTypes } from '@walletconnect/types';
+import type { ChainIdParams } from 'caip';
 import type { BlockchainMeta } from 'rango-types';
-export interface Environments extends Record<string, string | undefined> {
+import { SignClient } from '@walletconnect/sign-client';
+export { SignClient };
+export type SignClientInstance = InstanceType<typeof SignClient>;
+export interface Environments {
     WC_PROJECT_ID: string;
     DISABLE_MODAL_AND_OPEN_LINK?: string;
+    meta?: BlockchainMeta[];
+    themeMode?: 'light' | 'dark';
+    modalZIndex?: number;
 }
-export interface WCInstance {
-    client: SignClient;
-    session: SessionTypes.Struct | null;
-    request: (params: any) => Promise<string>;
-}
+export type WalletConnectNamespace = 'evm' | 'utxo';
 export interface CreateSessionParams {
-    requiredNamespaces: ProposalTypes.RequiredNamespaces;
-    optionalNamespaces?: ProposalTypes.OptionalNamespaces;
+    /**
+     * The whole proposal goes here - sign-client folds `requiredNamespaces` into
+     * this and clears it, so proposing anything as required is deprecated.
+     */
+    optionalNamespaces: ProposalTypes.OptionalNamespaces;
     pairingTopic?: string;
 }
 export interface ConnectParams {
-    meta: BlockchainMeta[];
+    /**
+     * Chains to propose, as CAIP-2 ids. Callers convert rango `BlockchainMeta`
+     * at the boundary (see `evmMetaToCaipChainIds`) so the connect path stays
+     * decoupled from rango-types' chain shape.
+     */
+    chains: ChainIdParams[];
     envs: Environments;
+    namespace: WalletConnectNamespace;
+    /**
+     * Decimal EVM chain reference (e.g. `"137"`).
+     * When set, it is the only EVM chain proposed during session creation.
+     */
+    chainReference?: string;
 }
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IAEtB,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,IAAI,CAAC,EAAE,cAAc,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,kBAAkB,EAAE,aAAa,CAAC,kBAAkB,CAAC;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,sBAAsB,CAAC;IAClC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/utils.d.ts

@@ -0,0 +1,17 @@
+import type { Chain } from '@hub3js/evm';
+import type { ChainIdParams } from 'caip';
+import type { BlockchainMeta } from 'rango-types';
+export declare function utf8ToHex(value: string, prefixed?: boolean): string;
+/** Normalizes hub chain input (hex, decimal, or AddEthereumChainParameter) to a decimal reference. */
+export declare function parseChainReference(chain?: string | Chain): string | undefined;
+/** Maps a chain reference to a Rango network name using blockchain meta. */
+export declare function resolveNetworkName(chain: string | Chain | null | undefined, meta: BlockchainMeta[]): string | undefined;
+/** Converts a decimal EVM chain reference to the `0x`-prefixed hex expected by hub EVM actions. */
+export declare function chainReferenceToHex(reference: string): `0x${string}`;
+/**
+ * Converts rango EVM blockchain meta to CAIP-2 chain ids - the only chain data the
+ * connect/proposal path needs. This is the single boundary where rango-types' chain
+ * shape is translated; everything downstream uses caip's ChainIdParams.
+ */
+export declare function evmMetaToCaipChainIds(meta: BlockchainMeta[]): ChainIdParams[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,MAAM,CAMjE;AAED,sGAAsG;AACtG,wBAAgB,mBAAmB,CACjC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GACrB,MAAM,GAAG,SAAS,CAYpB;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,EACxC,IAAI,EAAE,cAAc,EAAE,GACrB,MAAM,GAAG,SAAS,CAWpB;AAED,mGAAmG;AACnG,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,aAAa,EAAE,CAK7E"}

package/dist/wcConstants.d.ts

@@ -0,0 +1,61 @@
+/**
+ * WalletConnect protocol constants shared across the hub path (session/,
+ * adapter/, signers/, namespaces/). Kept separate from `constants.ts` (which
+ * holds the hub provider identity/metadata) so this module stays a dependency
+ * leaf and importing it never pulls in the signer/provider graph (the
+ * `WalletConnectNamespace` import below is type-only, so it is erased at runtime).
+ */
+import type { WalletConnectNamespace } from './types.js';
+export declare const PING_TIMEOUT = 10000;
+export declare enum NAMESPACES {
+    ETHEREUM = "eip155",
+    BITCOIN = "bip122",
+    POLKADOT = "polkadot",
+    CARDANO = "cip34",
+    ERLOND = "elrond",
+    MULTIVERSX = "multiversx"
+}
+/**
+ * Single source of truth for the namespace-alias -> CAIP-2 prefix relationship
+ * (`evm -> eip155`, `utxo -> bip122`). `proposals` and `lookup` read from this
+ * instead of re-encoding it. `Record<WalletConnectNamespace, …>` makes a new
+ * alias a compile error until it's mapped.
+ */
+export declare const WC_NAMESPACE_TO_CAIP: Record<WalletConnectNamespace, string>;
+export declare const CHAIN_ID_STORAGE = "wc@2:client//namespaces";
+export declare enum EthereumRPCMethods {
+    PERSONAL_SIGN = "personal_sign",
+    SIGN = "eth_sign",
+    SIGN_TYPED_DATA = "eth_signTypedData",
+    SIGN_TRANSACTION = "eth_signTransaction",
+    SEND_TRANSACTION = "eth_sendTransaction",
+    SEND_RAW_TRANSACTION = "eth_sendRawTransaction",
+    SWITCH_CHAIN = "wallet_switchEthereumChain",
+    ADD_CHAIN = "wallet_addEthereumChain",
+    GET_CHAIN = "eth_chainId"
+}
+export declare enum EthereumEvents {
+    CHAIN_CHANGED = "chainChanged",
+    ACCOUNTS_CHANGED = "accountsChanged"
+}
+export declare const DEFAULT_ETHEREUM_EVENTS: EthereumEvents[];
+export declare const DEFAULT_ETHEREUM_METHODS: EthereumRPCMethods[];
+export declare enum BitcoinRPCMethods {
+    SIGN_PSBT = "signPsbt",
+    GET_ACCOUNT_ADDRESSES = "getAccountAddresses",
+    SIGN_MESSAGE = "signMessage",
+    SEND_TRANSFER = "sendTransfer"
+}
+export declare enum BitcoinEvents {
+    ADDRESSES_CHANGED = "bip122_addressesChanged"
+}
+export declare const DEFAULT_BITCOIN_EVENTS: BitcoinEvents[];
+export declare const DEFAULT_BITCOIN_METHODS: BitcoinRPCMethods[];
+export declare const DEFAULT_APP_METADATA: {
+    name: string;
+    description: string;
+    url: string;
+    icons: string[];
+};
+export declare const RELAY_URL = "wss://relay.walletconnect.com";
+//# sourceMappingURL=wcConstants.d.ts.map

package/dist/wcConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wcConstants.d.ts","sourceRoot":"","sources":["../src/wcConstants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,eAAO,MAAM,YAAY,QAAS,CAAC;AAEnC,oBAAY,UAAU;IACpB,QAAQ,WAAW;IACnB,OAAO,WAAW;IAClB,QAAQ,aAAa;IACrB,OAAO,UAAU;IACjB,MAAM,WAAW;IACjB,UAAU,eAAe;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAGvE,CAAC;AAEF,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAG1D,oBAAY,kBAAkB;IAC5B,aAAa,kBAAkB;IAC/B,IAAI,aAAa;IACjB,eAAe,sBAAsB;IACrC,gBAAgB,wBAAwB;IACxC,gBAAgB,wBAAwB;IACxC,oBAAoB,2BAA2B;IAC/C,YAAY,+BAA+B;IAC3C,SAAS,4BAA4B;IACrC,SAAS,gBAAgB;CAC1B;AAED,oBAAY,cAAc;IACxB,aAAa,iBAAiB;IAC9B,gBAAgB,oBAAoB;CACrC;AAED,eAAO,MAAM,uBAAuB,EAAE,cAAc,EAGnD,CAAC;AAEF,eAAO,MAAM,wBAAwB,sBAOpC,CAAC;AAGF,oBAAY,iBAAiB;IAC3B,SAAS,aAAa;IACtB,qBAAqB,wBAAwB;IAC7C,YAAY,gBAAgB;IAC5B,aAAa,iBAAiB;CAC/B;AAED,oBAAY,aAAa;IACvB,iBAAiB,4BAA4B;CAC9C;AAED,eAAO,MAAM,sBAAsB,EAAE,aAAa,EAEjD,CAAC;AAEF,eAAO,MAAM,uBAAuB,qBAGnC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;CAKhC,CAAC;AAEF,eAAO,MAAM,SAAS,kCAAkC,CAAC"}

package/package.json

@@ -1,41 +1,46 @@
 {
   "name": "@rango-dev/provider-walletconnect-2",
-  "version": "0.57.0",
+  "version": "0.57.1-next.0",
   "license": "MIT",
   "type": "module",
-  "source": "./src/index.ts",
-  "main": "./dist/index.js",
+  "source": "./src/mod.ts",
+  "main": "./dist/mod.js",
   "exports": {
-    ".": "./dist/index.js"
+    ".": "./dist/mod.js"
   },
-  "typings": "dist/index.d.ts",
+  "typings": "dist/mod.d.ts",
   "files": [
     "dist",
     "src"
   ],
   "scripts": {
-    "build": "yarn run rangutopia library build --splitting --external-all-except @walletconnect/modal",
+    "build": "yarn run rangutopia library build --splitting",
     "ts-check": "tsc --declaration --emitDeclarationOnly -p ./tsconfig.json",
     "clean": "rimraf dist",
     "format": "prettier --write '{.,src}/**/*.{ts,tsx}'",
     "lint": "eslint \"**/*.{ts,tsx}\""
   },
   "dependencies": {
+    "@bitcoinerlab/secp256k1": "^1.2.0",
+    "@hub3js/core": "^0.61.0",
+    "@hub3js/evm": "^0.3.3",
+    "@hub3js/std": "^0.2.3",
     "@rango-dev/logging-core": "^0.14.0",
     "@rango-dev/signer-evm": "^0.45.0",
-    "@rango-dev/signer-solana": "^0.49.0",
-    "@rango-dev/wallets-shared": "^0.62.0",
-    "@solana/web3.js": "^1.91.4",
+    "@rango-dev/wallets-core": "^0.61.0",
+    "@rango-dev/wallets-shared": "^0.62.1-next.0",
+    "@reown/appkit": "1.8.20",
     "@walletconnect/encoding": "^1.0.2",
-    "@walletconnect/sign-client": "^2.11.2",
-    "@walletconnect/utils": "^2.11.2",
+    "@walletconnect/sign-client": "2.23.7",
+    "@walletconnect/universal-provider": "2.23.7",
+    "@walletconnect/utils": "2.23.7",
+    "bitcoinjs-lib": "^6.1.7",
     "bs58": "^5.0.0",
     "caip": "^1.1.1",
     "rango-types": "^0.5.0"
   },
   "devDependencies": {
-    "@walletconnect/modal": "^2.6.2",
-    "@walletconnect/types": "^2.11.2"
+    "@walletconnect/types": "2.23.7"
   },
   "publishConfig": {
     "access": "public"

package/readme.md

@@ -1,8 +1,20 @@
-# @rango-dev/provider-walletconnect2
+# WalletConnect
 
+WalletConnect integration for hub.
+[Homepage](https://walletconnect.com/) | [Docs](https://docs.walletconnect.com/)
+
+More about implementation status can be found [here](../readme.md).
+
+## Implementation notes/limitations
+
+### Group
+
+#### ⚠️ UTXO
+
+Only supports Bitcoin.
 
 ## Known issues
 
-- Using Private key to import wallets other than `Ethereum` will be problematic. Because it imports only a single blockchain and we are by default asking for `Ethereum`.  
+- Using Private key to import wallets other than `Ethereum` will be problematic. Because it imports only a single blockchain and we are by default asking for `Ethereum`.
 - Signing a transaction on Metamask goes through an internal error.
 - We couldn't update exist session during a bug in `@walletconnect/utils`, so we are creating new session for accessing to new chains.

package/src/adapter/adapter.ts

@@ -0,0 +1,289 @@
+import type { WalletConnectNamespace } from '../types.js';
+import type { Chain } from '@hub3js/evm';
+import type { SessionTypes } from '@walletconnect/types';
+import type UniversalProvider from '@walletconnect/universal-provider';
+import type { BlockchainMeta } from 'rango-types';
+
+import { debug } from '@rango-dev/logging-core';
+
+import {
+  ensureConnectedToChain as ensureConnectedToChainHelper,
+  getCurrentChainId as getCurrentChainIdHelper,
+  resolveActiveChainReference as resolveActiveChainReferenceHelper,
+  switchEvmNetwork as switchEvmNetworkHelper,
+} from '../session/evm-chain.js';
+import {
+  connectWalletConnectSession,
+  prepareWalletConnectNamespace,
+} from '../session/lifecycle.js';
+import { restoreAndCacheSession } from '../session/restore-cache.js';
+import { removeSessionRecord } from '../session/teardown.js';
+import { evmMetaToCaipChainIds } from '../utils.js';
+
+import { ModalCache } from './modal-cache.js';
+import { createUniversalProvider } from './provider-client.js';
+import { createSessionCache } from './session-cache.js';
+import { TaskQueue } from './task-queue.js';
+
+/**
+ * Central coordinator for WalletConnect sessions used by hub EVM/UTXO namespaces.
+ *
+ * Owns provider state (client, session cache, modal) and delegates protocol/domain
+ * logic to `session/*` helpers.
+ */
+export interface WalletConnectAdapterConfig {
+  projectId: string;
+  meta: BlockchainMeta[];
+  disableModalLink?: string;
+  themeMode?: 'light' | 'dark';
+  modalZIndex?: number;
+}
+
+export class WalletConnectAdapter {
+  readonly #projectId: string;
+  readonly #disableModalLink?: string;
+  readonly #themeMode?: 'light' | 'dark';
+  readonly #modalZIndex?: number;
+  readonly #meta: BlockchainMeta[];
+  #universalProvider: UniversalProvider | null = null;
+  #universalProviderPromise: Promise<UniversalProvider> | null = null;
+
+  readonly #cache = createSessionCache();
+  readonly #modalCache = new ModalCache();
+
+  /**
+   * Serializes everything that mutates WalletConnect session state.
+   *
+   * Connecting and disconnecting must never overlap: tearing a session down also
+   * deletes its pairing, and an overlapping connect has already minted a new one
+   * by then - the teardown unsubscribes it, so `wc_proposeSession` publishes to a
+   * topic we no longer listen on and the relay answers
+   * `Topic repository: AlreadyExists`.
+   *
+   * The hub can't order this for us: `useHubAdapter.disconnect` drops the
+   * promises `namespace.disconnect()` returns (it iterates with `forEach`), so it
+   * resolves while teardown is still in flight and never joins the queue that
+   * serializes `connect`.
+   *
+   * The cost is that a connect holds the queue for its whole lifetime, including
+   * the wait for the user to approve in their wallet, so a disconnect raised
+   * meanwhile waits its turn instead of interleaving. That is deliberate rather
+   * than an oversight: the pairing has to survive from `client.connect()` through
+   * settle, which is exactly the span being protected.
+   */
+  readonly #sessionQueue = new TaskQueue();
+
+  constructor(config: WalletConnectAdapterConfig) {
+    this.#projectId = config.projectId;
+    this.#meta = config.meta;
+    this.#disableModalLink = config.disableModalLink;
+    this.#themeMode = config.themeMode;
+    this.#modalZIndex = config.modalZIndex;
+  }
+
+  async getUniversalProvider(): Promise<UniversalProvider> {
+    /*
+     * Memoize the in-flight promise, not the resolved value. A namespace's
+     * `before` subscribers are invoked with `forEach` (nothing awaits between
+     * them), so several reach this method in the same tick - awaiting first and
+     * assigning after would let each start its own `UniversalProvider`, leaving
+     * several SignClients sharing one storage. The extra clients answer relay
+     * traffic for a handshake they never made ("Pending session not found for
+     * topic X", then "No matching key. session topic doesn't exist: X").
+     */
+    if (!this.#universalProviderPromise) {
+      this.#universalProviderPromise = createUniversalProvider(this.#projectId)
+        .then((provider) => {
+          this.#universalProvider = provider;
+          return provider;
+        })
+        .catch((error: unknown) => {
+          // Don't cache a failed init - let the next caller retry.
+          this.#universalProviderPromise = null;
+          throw error;
+        });
+    }
+
+    return this.#universalProviderPromise;
+  }
+
+  async getClient() {
+    return (await this.getUniversalProvider()).client;
+  }
+
+  getSession(namespace: WalletConnectNamespace): SessionTypes.Struct | null {
+    return this.#cache.get(namespace);
+  }
+
+  cacheSession(
+    namespace: WalletConnectNamespace,
+    session: SessionTypes.Struct
+  ) {
+    this.#cache.set(namespace, session);
+  }
+
+  clearSession(namespace: WalletConnectNamespace) {
+    this.#cache.clear(namespace);
+  }
+
+  clearAllSessions() {
+    this.#cache.clearAll();
+  }
+
+  async tryRestoreEagerSession(
+    namespace: WalletConnectNamespace
+  ): Promise<boolean> {
+    return this.#sessionQueue.run(async () => {
+      const client = await this.getClient();
+      return !!(await restoreAndCacheSession(
+        client,
+        namespace,
+        this.#cache,
+        { validateAccounts: true },
+        async (targetNamespace) =>
+          this.#disconnectSessionQueued(targetNamespace)
+      ));
+    });
+  }
+
+  async ensureSession(options: {
+    namespace: WalletConnectNamespace;
+    chainReference?: string;
+  }): Promise<SessionTypes.Struct> {
+    return this.#sessionQueue.run(async () =>
+      this.#ensureSessionQueued(options)
+    );
+  }
+
+  async disconnectSession(namespace: WalletConnectNamespace) {
+    return this.#sessionQueue.run(async () =>
+      this.#disconnectSessionQueued(namespace)
+    );
+  }
+
+  async resolveActiveChainReference(): Promise<string | undefined> {
+    const session = this.getSession('evm');
+    if (!session) {
+      return undefined;
+    }
+
+    return resolveActiveChainReferenceHelper(await this.getClient(), session);
+  }
+
+  async getCurrentChainId(): Promise<`0x${string}`> {
+    const session = this.getSession('evm');
+    if (!session) {
+      throw new Error(
+        'Unable to determine EVM chain id from WalletConnect session.'
+      );
+    }
+
+    return getCurrentChainIdHelper(await this.getClient(), session);
+  }
+
+  async ensureConnectedToChain(
+    chain?: string | Chain
+  ): Promise<SessionTypes.Struct> {
+    return ensureConnectedToChainHelper(this.#evmChainDeps(), chain);
+  }
+
+  async switchEvmNetwork(
+    requestedChainId: string,
+    currentChainId: string
+  ): Promise<void> {
+    const session = this.getSession('evm');
+    if (!session) {
+      throw new Error('WalletConnect session is not available.');
+    }
+
+    this.cacheSession(
+      'evm',
+      await switchEvmNetworkHelper({
+        client: await this.getClient(),
+        session,
+        meta: this.#meta,
+        requestedChainId,
+        currentChainId,
+      })
+    );
+  }
+
+  /*
+   * The `Queued` suffix means "already running inside `#sessionQueue`". These
+   * call each other directly and must never go back through the public methods
+   * above: re-entering the queue from inside a task would wait for a turn that
+   * cannot come until that same task finishes, which deadlocks.
+   */
+
+  async #ensureSessionQueued(options: {
+    namespace: WalletConnectNamespace;
+    chainReference?: string;
+  }): Promise<SessionTypes.Struct> {
+    const { namespace, chainReference } = options;
+    const client = await this.getClient();
+    const restored = await restoreAndCacheSession(
+      client,
+      namespace,
+      this.#cache,
+      undefined,
+      async (targetNamespace) => this.#disconnectSessionQueued(targetNamespace)
+    );
+    if (restored) {
+      return restored;
+    }
+
+    await prepareWalletConnectNamespace(client, namespace);
+
+    const universalProvider = await this.getUniversalProvider();
+    await universalProvider.cleanupPendingPairings().catch(() => undefined);
+
+    const session = await connectWalletConnectSession(
+      client,
+      this.#modalCache.getModal({
+        projectId: this.#projectId,
+        universalProvider,
+        themeMode: this.#themeMode,
+        zIndex: this.#modalZIndex,
+      }),
+      {
+        chains: evmMetaToCaipChainIds(this.#meta),
+        envs: {
+          WC_PROJECT_ID: this.#projectId,
+          DISABLE_MODAL_AND_OPEN_LINK: this.#disableModalLink,
+        },
+        namespace,
+        chainReference,
+      }
+    );
+
+    this.#cache.set(namespace, session);
+    return session;
+  }
+
+  async #disconnectSessionQueued(namespace: WalletConnectNamespace) {
+    const session = this.getSession(namespace);
+    if (this.#universalProvider?.client && session) {
+      await removeSessionRecord(this.#universalProvider.client, session).catch(
+        (error) => debug(error)
+      );
+    }
+    this.clearSession(namespace);
+    if (session) {
+      this.#cache.clearTopic(session.topic);
+    }
+  }
+
+  #evmChainDeps() {
+    return {
+      meta: this.#meta,
+      getSession: (namespace: 'evm') => this.getSession(namespace),
+      cacheSession: (namespace: 'evm', session: SessionTypes.Struct) =>
+        this.cacheSession(namespace, session),
+      getClient: async () => this.getClient(),
+      ensureSession: async (options: {
+        namespace: 'evm';
+        chainReference?: string;
+      }) => this.ensureSession(options),
+    };
+  }
+}

package/src/adapter/index.ts

@@ -0,0 +1,2 @@
+export { WalletConnectAdapter } from './adapter.js';
+export { type AppKitModal, createAppKitModal } from './modal.js';

package/src/adapter/modal-cache.ts

@@ -0,0 +1,23 @@
+import type { AppKitModal, ModalParams } from './modal.js';
+
+import { createAppKitModal } from './modal.js';
+
+/**
+ * Holds the single AppKit modal for the adapter's lifetime.
+ *
+ * One instance serves every namespace - all its networks are registered up front
+ * and the active one is chosen per connect with `switchNetwork`. It is built once
+ * and reused: rebuilding per namespace re-ran AppKit init against its shared
+ * singleton controllers and left stale router/filter state behind.
+ */
+export class ModalCache {
+  #web3Modal: AppKitModal | null = null;
+
+  getModal(params: ModalParams): AppKitModal {
+    if (!this.#web3Modal) {
+      this.#web3Modal = createAppKitModal(params);
+    }
+
+    return this.#web3Modal;
+  }
+}