This guide provides a step-by-step approach to integrating Ethereum Virtual Machine (EVM) wallet support into your NEAR decentralized applications (dApps). By following these instructions, you can enable users to connect with popular Ethereum wallets like MetaMask while maintaining compatibility with the NEAR Wallet Selector.
Prerequisites
Before starting, ensure your dApp already uses the NEAR Wallet Selector. This integration extends its functionality to include EVM-compatible wallets.
You will need to update existing libraries and add new dependencies to facilitate communication between Ethereum wallets and NEAR's Remote Procedure Calls (RPCs).
Required Library Updates
Wallet Selector Packages
Begin by updating your package.json file. Upgrade all existing @near-wallet-selector packages to version 8.9.13 or higher. Additionally, include the Ethereum wallets package:
"dependencies": {
"@near-wallet-selector/core": "^8.9.13",
"@near-wallet-selector/ethereum-wallets": "^8.9.13",
"@near-wallet-selector/here-wallet": "^8.9.13",
"@near-wallet-selector/modal-ui": "^8.9.13",
"@near-wallet-selector/my-near-wallet": "^8.9.13"
}Web3Modal Integration
Web3Modal (also known as AppKit) serves as the standard interface for integrating multiple Ethereum wallets. Install these essential libraries:
npm install @web3modal/wagmi wagmi viem @tanstack/react-queryThis setup uses wagmi hooks for React applications. For other frameworks, consult the Web3Modal documentation for platform-specific instructions.
Configuration Setup
NEAR Chain Configuration
Create a configuration file that allows MetaMask and other EVM wallets to communicate with NEAR RPC endpoints. This configuration bridges the gap between Ethereum-style transactions and the NEAR blockchain.
Proper configuration ensures that transactions initiated through EVM wallets are correctly routed and processed by NEAR's network infrastructure.
Web3Modal Implementation
Develop a dedicated handler file for Web3Modal functionality. This component manages the modal interface that appears when users select "Ethereum Wallets" from the Wallet Selector.
👉 Explore more strategies for wallet integration
Important: Implement reconnect functionality within your wagmi configuration to maintain persistent connections between your application and user wallets, even after page refreshes.
Project Identification
Web3Modal requires a unique projectId associated with your project on the Reown platform. Obtain this identifier by:
- Registering an account on Cloud Reown
- Creating a new project within the platform
- Copying the generated
projectIdfor use in your configuration
This identifier helps manage wallet connections and provides analytics for your dApp's wallet usage.
Implementation Steps
Wallet Selector Setup
Modify your existing setupWalletSelector call to include Ethereum wallet support. Import the necessary modules and integrate the Ethereum wallets setup:
import { setupWalletSelector } from '@near-wallet-selector/core';
import { wagmiConfig, web3Modal } from '@/wallets/web3modal';
import { setupEthereumWallets } from "@near-wallet-selector/ethereum-wallets";This integration ensures that both NEAR-native and EVM-compatible wallets appear as options in your wallet selection interface.
Testing and Deployment
After implementing these changes, rebuild your project and test the login functionality. You should now see an "Ethereum Wallets" option within your NEAR Wallet Selector.
Upon selecting this option, users should be presented with a choice of supported EVM wallets, creating a seamless cross-chain experience.
Technical Background
The ability to integrate EVM wallets with NEAR dApps represents significant technical advancement achieved through the NEP-518 standard. This development enables Ethereum addresses to interact directly with NEAR protocols through sophisticated RPC routing and transaction translation mechanisms.
The implementation maintains security standards while providing users with familiar wallet interfaces, thereby enhancing accessibility across blockchain ecosystems.
Frequently Asked Questions
Why should I integrate EVM wallets with my NEAR dApp?
Integrating EVM wallets expands your potential user base by allowing Ethereum users to access your dApp without creating new NEAR-specific wallets. This reduces friction for adoption while maintaining the security and functionality of both ecosystems.
What are the main technical challenges in this integration?
The primary challenges involve configuring proper RPC communication between Ethereum-style transactions and NEAR's blockchain architecture. Additionally, maintaining persistent connections and handling transaction formatting between different standards requires careful implementation.
Can I use this integration with any EVM-compatible wallet?
Yes, the Web3Modal approach supports multiple EVM-compatible wallets through a standardized interface. The configuration works with MetaMask, WalletConnect, and other popular options that follow Ethereum standards.
How does this affect transaction fees and gas costs?
Transactions still occur on the NEAR network, so users benefit from NEAR's low transaction fees. The integration simply allows Ethereum wallets to initiate these transactions through appropriate RPC routing.
Is user education required for this wallet integration?
Most Ethereum wallet users will find the interface familiar, though some may need clarification that they're interacting with the NEAR blockchain. Clear UI indicators help communicate which network they're using during transactions.
What backup options should I provide for wallet connection issues?
Always maintain the original NEAR wallet options alongside EVM support. This ensures users have fallback connection methods if they experience issues with their Ethereum wallet integration.
Additional Resources
For deeper understanding, examine the source code of implementation examples and review the technical specifications in NEP-518. These resources provide comprehensive details about on-chain execution and wallet communication protocols.
This integration represents a significant step toward blockchain interoperability, allowing developers to leverage user bases from multiple ecosystems while maintaining a consistent dApp experience.