chore: move adapter blueprint to controllers

[tomiir]

Description

🔄 Refactor: Move ChainAdapterBlueprint to Controllers Package

Overview

This PR refactors the adapter architecture by relocating ChainAdapterBlueprint from individual adapter packages to the @reown/appkit-controllers package, making it centrally available for use by AdapterController. This change eliminates the need for a centralized connectionManager and simplifies adapter implementations while improving error handling and resolving circular dependencies.

🎯 Key Changes

Architecture Improvements

• 📦 Blueprint Relocation: Moved ChainAdapterBlueprint from adapter packages to packages/controllers/src/controllers/AdapterController/ChainAdapterBlueprint.ts
• 🔌 Decentralized Connection Management: Removed dependency on centralized connectionManager - each adapter now implements syncConnections independently
• 🎛️ Controller Integration: Wired ChainAdapterBlueprint into AdapterController for centralized adapter management
• 🔄 Circular Dependency Resolution: Fixed circular import issues between packages by restructuring dependencies

Enhanced Error Handling

• 🚨 Improved User Rejection Detection: Enhanced ErrorUtil.isUserRejectedRequestError() to handle multiple error codes:
  • USER_REJECTED_REQUEST (4001)
  • USER_REJECTED_METHODS (5002)
  • USER_REJECTED (5000) - newly added
• 📝 Better Error Messages: Improved error message matching for user rejection scenarios (case-insensitive detection)
• 🎯 WalletConnect Error Handling: Added dedicated WcHelpersUtil.isUserRejectedRequestError() for WalletConnect-specific error codes
• 📊 Enhanced Telemetry: Better error tracking and event emission for user rejection vs connection errors

Adapter Simplifications

• 🔧 Method Simplification: Adapter methods no longer require prop drill-down patterns
• ⚡ Direct Implementation: Each adapter (Bitcoin, Ethers, Ethers5, Solana, Wagmi) now implements syncConnections directly using their respective controllers and clients
• 🧹 Cleaner APIs: Removed complex connection management abstractions in favor of straightforward, adapter-specific implementations

Updated Components

• Controllers: WalletConnectConnector, ChainController, OptionsController, ProviderController, WalletConnectUtil
• Adapters: All five adapters (Bitcoin, Ethers, Ethers5, Solana, Wagmi) updated with new connection sync patterns
• AppKit Core: Updated appkit-base-client, appkit-core, universal adapter client, and utilities (BalanceUtil, ConstantsUtil)
• UI Components: Enhanced error handling in connection views (w3m-connecting-wc-view)
• Tests: Comprehensive test updates across all affected packages to align with new architecture

Dependency Management

• 📌 Strict Versioning: Updated to use strict version constraints across packages to prevent version conflicts
• 🔒 Package Consistency: Synchronized dependency versions across the monorepo using workspace:* notation
• 📦 Export Cleanup: Removed circular imports and cleaned up package exports to prevent bundling issues

🏗️ Technical Benefits

1. Better Separation of Concerns: Blueprint logic is now centralized in controllers where it belongs
2. Reduced Complexity: Eliminates the need for complex connection manager abstractions
3. Improved Maintainability: Each adapter manages its own connection lifecycle more directly
4. Enhanced Testability: Simpler adapter interfaces make unit testing more straightforward
5. Robust Error Handling: Comprehensive error detection and user feedback mechanisms
6. Dependency Clarity: Resolved circular dependencies for cleaner build processes

🔧 Implementation Details

Before: Adapters relied on a shared connectionManager with complex prop drilling

// Complex connection management through centralized manager
adapter.connectionManager.syncConnections(params)

After: Each adapter implements syncConnections directly

// Direct, adapter-specific implementation
adapter.syncConnections({ connectToFirstConnector, caipNetwork })

Error Handling Enhancement:

// Before: Limited error code detection
isUserRejectedCode = error.code === 4001

// After: Comprehensive error detection
isUserRejectedCode || isUserRejectedMethodsCode || ErrorUtil.isUserRejectedMessage(error.message)

🐛 Bug Fixes & Improvements

• 🔧 Type Safety: Fixed TypeScript compilation issues across adapters
• 🎨 Code Formatting: Applied consistent prettier formatting across all modified files
• 🧪 Test Coverage: Updated and expanded test suites for new adapter patterns
• 📝 Linting: Resolved ESLint issues and enforced consistent code style
• 🔗 Import Optimization: Fixed import paths to use package exports instead of deep imports

📋 Migration Impact

• ✅ Non-breaking: Public APIs remain unchanged
• 🔄 Internal Refactor: Changes are primarily internal to adapter implementations
• 📦 Package Updates: Updated exports and manifests across affected packages
• 🔒 Lockfile Refresh: Dependencies updated to reflect new internal structure
• ⚡ Performance: Reduced bundle size through elimination of circular dependencies

🧪 Testing

• All existing unit tests updated to work with new architecture
• New tests added for adapter-specific syncConnections implementations
• Enhanced error handling test coverage for user rejection scenarios
• Integration tests verify that connection management still works correctly across all supported chains
• Comprehensive test coverage for circular dependency prevention

🚀 Deployment

• Preview deployments successful across all environments:
  • AppKit Laboratory ✅
  • AppKit Gallery ✅
  • AppKit Demo ✅
  • Basic HTML Examples ✅

This refactoring sets the foundation for more maintainable adapter development while preserving all existing functionality, improving error handling, and establishing a cleaner architecture for the AppKit SDK.

Type of change

• Chore (non-breaking change that addresses non-functional tasks, maintenance, or code quality improvements)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• Code in this PR is covered by automated tests (Unit tests, E2E tests)
• My changes generate no new warnings
• I have reviewed my own code
• I have filled out all required sections
• I have tested my changes on the preview link
• Approver of this PR confirms that the changes are tested on the preview link

---

Note

Centralizes ChainAdapterBlueprint in controllers, refactors adapters to implement syncConnections, and improves user-rejection error handling across SDK with aligned tests and exports.

• Controllers:
  • Move ChainAdapterBlueprint to packages/controllers/src/controllers/AdapterController/ChainAdapterBlueprint.ts and integrate with AdapterController.
  • Update ChainController, OptionsController, ProviderController, WalletConnectConnector, and WalletConnectUtil for new adapter flow.
• Adapters:
  • Refactor bitcoin, ethers, ethers5, solana, and wagmi clients/connectors to implement syncConnections directly; remove centralized connection manager patterns.
  • Update WalletConnect connectors/providers accordingly.
• Error Handling:
  • Expand user-rejection detection in ErrorUtil and add WalletConnect-specific helpers; standardize messages/events.
• AppKit:
  • Align appkit-base-client, appkit-core, universal adapter client, and utilities with new blueprint and connection model; update exports.
• UI:
  • Adjust connection views/widgets to new flow and error handling.
• Tests:
  • Update unit/e2e tests across adapters, controllers, and appkit; add coverage for syncConnections and rejection cases.
• Repo Hygiene:
  • Sync package versions/exports across monorepo; minor workflow update in .github/workflows/release-publish.yml; refresh changelogs.

^{Written by Cursor Bugbot for commit e2ab0c3. This will update automatically on new commits. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: e2ab0c3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 24 packages

Name	Type
@reown/appkit-controllers	Patch
@reown/appkit-scaffold-ui	Patch
@reown/appkit-adapter-bitcoin	Patch
@reown/appkit-adapter-ethers	Patch
@reown/appkit-adapter-ethers5	Patch
@reown/appkit-adapter-solana	Patch
@reown/appkit-adapter-wagmi	Patch
@reown/appkit	Patch
@reown/appkit-ui	Patch
@reown/appkit-core	Patch
@reown/appkit-utils	Patch
@reown/appkit-siwe	Patch
@reown/appkit-siwx	Patch
@reown/appkit-wallet-button	Patch
@reown/appkit-experimental	Patch
@reown/appkit-pay	Patch
@reown/appkit-cdn	Patch
@reown/appkit-universal-connector	Patch
@reown/appkit-testing	Patch
@reown/appkit-common	Patch
@reown/appkit-polyfills	Patch
@reown/appkit-wallet	Patch
@reown/appkit-cli	Patch
@reown/appkit-codemod	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
appkit-basic-html	Ready	Preview	Comment	Oct 3, 2025 11:24am
appkit-demo	Ready	Preview	Comment	Oct 3, 2025 11:24am
appkit-gallery	Ready	Preview	Comment	Oct 3, 2025 11:24am
appkit-laboratory	Ready	Preview	Comment	Oct 3, 2025 11:24am

10 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
appkit-basic-example	Ignored			Oct 3, 2025 11:24am
appkit-basic-sign-client-example	Ignored			Oct 3, 2025 11:24am
appkit-basic-up-example	Ignored			Oct 3, 2025 11:24am
appkit-ethers5-bera	Ignored			Oct 3, 2025 11:24am
appkit-nansen-demo	Ignored			Oct 3, 2025 11:24am
appkit-vue-solana	Ignored			Oct 3, 2025 11:24am
appkit-wagmi-cdn-example	Ignored			Oct 3, 2025 11:24am
ethereum-provider-wagmi-example	Ignored			Oct 3, 2025 11:24am
next-wagmi-solana-bitcoin-example	Ignored			Oct 3, 2025 11:24am
vue-wagmi-example	Ignored			Oct 3, 2025 11:24am

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​exodus/​bitcoin-wallet-standard@​0.0.0
	@​radix-ui/​react-label@​2.1.7
	@​radix-ui/​react-separator@​1.1.7
	@​changesets/​changelog-github@​0.5.1
	@​radix-ui/​react-slot@​1.2.3
	@​radix-ui/​react-switch@​1.2.6
	@​radix-ui/​react-tabs@​1.1.13
	@​dnd-kit/​utilities@​3.2.2
	@​chakra-ui/​icons@​2.2.6
	@​radix-ui/​react-checkbox@​1.3.3
	@​radix-ui/​react-radio-group@​1.3.8
	@​babel/​preset-react@​7.27.1
	@​esbuild-plugins/​node-globals-polyfill@​0.2.3
	@​radix-ui/​react-accordion@​1.2.12
	@​radix-ui/​react-dialog@​1.1.15
	@​radix-ui/​react-tooltip@​1.2.8
	@​radix-ui/​react-slider@​1.3.6
	@​radix-ui/​react-select@​2.2.6
	@​leather.io/​rpc@​2.1.21
	@​babel/​plugin-transform-runtime@​7.27.4
	@​babel/​preset-env@​7.27.2
	@​babel/​preset-env@​7.24.7
	@​bitcoinerlab/​secp256k1@​1.2.0
	@​dnd-kit/​core@​6.3.1
	@​reown/​appkit-testing@​1.8.4
	@​mailsac/​api@​1.0.8
	@​babel/​runtime@​7.28.4
	@​dnd-kit/​sortable@​9.0.0
	@​phosphor-icons/​webcomponents@​2.1.5
	@​safe-global/​safe-apps-sdk@​9.1.0
	@​next/​third-parties@​15.2.1
	@​safe-global/​safe-apps-provider@​0.18.6
	@​eslint/​eslintrc@​3.3.1
See 29 more rows in the dashboard

View full report

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report