From 72e337c7368a9badc0d84a1b091e8958fa549853 Mon Sep 17 00:00:00 2001 From: Michael Birch Date: Mon, 22 Jul 2024 19:57:56 +0200 Subject: [PATCH] NEP-518 description from #518 --- neps/nep-0518.md | 337 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 neps/nep-0518.md diff --git a/neps/nep-0518.md b/neps/nep-0518.md new file mode 100644 index 000000000..34c1d5dcf --- /dev/null +++ b/neps/nep-0518.md @@ -0,0 +1,337 @@ +--- +NEP: 518 +Title: Web3-Compatible Wallets Support +Authors: Aleksandr Shevchenko +Status: New +DiscussionsTo: https://github.com/near/NEPs/issues/518 +Type: Protocol +Version: 1.0.0 +Created: 2023-11-15 +LastUpdated: 2024-07-22 +--- + +## Summary + +This proposal introduces a significant enhancement to the NEAR Protocol, aiming to make its ecosystem closer with Ethereum by integrating Web3 wallet support. The primary goal is to resolve the incompatibility issues between Ethereum and NEAR standards, thus facilitating a seamless user experience for Ethereum users on the NEAR platform. Central to this initiative are several components: the Wallet Contract, Wallet Selector Extension, RPC-Translator, Transaction Relayer, and the Ethereum Translation Contract. Together, these elements enable Ethereum-compatible transactions within NEAR, ensuring that users familiar with Ethereum's environment face minimal friction in using NEAR dApps. + +Key features include a protocol change that embeds the Wallet Contract for implicit Ethereum-style accounts as a fundamental feature of NEAR and simulating Ethereum standards for transaction compatibility on the level of this contract. + +Proposal also acknowledges inherent limitations and risks, which, however, are manageable. The proposal outlines future opportunities for extending its capabilities to include more Ethereum standards and exploring further integrations. The project's scope is vast, requiring rigorous development, testing, and collaboration across various components and entities of the NEAR ecosystem. + +In essence, this proposal strives to enhance NEAR's interoperability with Ethereum, significantly improving accessibility and user experience for a broader audience in the blockchain community. + +The proposal has core and advanced topics. Pieces that are marked with **[COMPLEX]** may be omitted during the first read. + +## Problem Statement + +Currently, the Ethereum ecosystem is a leading force in the smart contract blockchain space, boasting a large user base and extensive installations of Ethereum-compatible tooling and wallets. However, a significant challenge arises due to the incompatibility of these tools and wallets with NEAR Protocol. This incompatibility necessitates a complete onboarding process for users to interact with NEAR contracts and accounts, leading to confusion, decreased adoption, and the marginalization of NEAR Protocol. + +Implementing Web3 wallet support in NEAR Protocol, with an emphasis on user experience continuity, would significantly benefit the entire NEAR Ecosystem. + +## Goals / Deliverables + +The primary goal is to develop a solution enabling Web3 wallet users to seamlessly interact with NEAR Protocol while retaining their user experience with other EVM-compatible networks. This solution should be straightforward, requiring minimal changes to the NEAR protocol, avoiding potential reversals of protocol changes, and minimizing the need for extensive user education. Additionally, it should prioritize minimizing the risk of phishing attacks that trick users into signing indecipherable data. It's crucial that transactions signed by users are processed unambiguously at the NEAR blockchain level, eliminating the need for a trusted intermediary. + +## Prior work + +Previous efforts have been made in this area. Notable examples include the [nEth](https://github.com/neardefi/neth) project and the [Metamask Snap for NEAR](https://github.com/here-wallet/near-snap). These projects enable Metamask compatibility with NEAR natively but fall short in supporting arbitrary Ethereum wallets. Moreover, neither project provides a user experience comparable to that of EVM-compatible chains. + +With nEth, users must sign [EIP-712](https://eips.ethereum.org/EIPS/eip-712) messages, which differs from executing standard transactions in Metamask. The Metamask Snap project effectively creates a distinct application within Metamask, separate from typical Metamask workflows. This application cannot interact with Metamask keys, nor can it display token balances or transaction histories, and it lacks integration with Ledger. Both projects also necessitate funding new accounts from external sources. + +[Aurora XCC](https://dev.aurora.dev/posts/cross-ecosystem-communication) offers another avenue for Ethereum wallet users to interact with Near native. However, this approach has drawbacks, such as the requirement for WNEAR (NEP-141 wrapped NEAR bridged into Aurora from Near native) for many applications. This necessity complicates users' understanding of transaction costs. Additionally, XCC introduces a gas overhead compared to direct Near usage, potentially hindering user interactions with some applications due to Near's 300 Tgas transaction limit. + +## Technical Description + +Ethereum and NEAR exhibit several fundamental incompatibilities that impact areas such as transaction formats, signature algorithms, addressing schemes, public RPC APIs, and interaction workflows. This proposal seeks to effectively conceal and/or resolve these incompatibilities to facilitate standard wallet operations like balance inquiries, account top-ups, transfers of fungible tokens, and smart contract function calls on the NEAR blockchain. + +### Solution Overview + +The proposed solution comprises five key components: + +1. **Wallet Contract (WC)**: An on-chain smart contract designed to receive, validate, and execute Ethereum-compatible transactions on the NEAR blockchain. It functions as a user account. + +2. **Wallet Selector Extension**: A frontend module that connects NEAR-compatible wallets to dApps. This project aims to develop add-ons supporting Ethereum wallets, primarily to create Ethereum-compatible transactions from NEAR-compatible inputs. + +3. **RPC-Translator (RPCT)**: Given that Ethereum wallets access blockchain state via a specific Web3 API, the RPC-Translator is designed to provide Ethereum methods implementations using the NEAR RPC as a data source. This component, along with the Transaction Relayer, is publicly hosted and accessible to all users. While the RPC-Translator and Transaction Relayer are operated together, they are listed separately to highlight their distinct functions. + +4. **Transaction Relayer (TR)**: Ethereum wallets cannot generate NEAR-compatible transactions. Instead, Ethereum-compatible transactions produced by them are processed by the Transaction Relayer, which embeds it into a NEAR transaction and forwards it to the user’s Wallet Contract. Again, while operated in conjunction with the RPC-Translator, the Transaction Relayer is distinct in its role. + +5. **[COMPLEX] Ethereum Translation Contract (ETC)**: Addressing the incompatibility between NEAR's human-readable account names and Ethereum's cryptographic hash-based addresses, the ETC functions as an on-chain mapping system. This system records NEAR-compatible input values (like NEAR account names and smart contract function names) and maps them to their corresponding Ethereum-compatible cryptographic hashes. This feature is vital for preserving familiar user experiences, such as recognizing ft_transfer operations in NEP-141 as fungible token (ERC20) transfers, rather than generic contract calls, and ensuring that fungible token balances are displayed in Web3 wallets. + +### Transaction Flow + +The transaction flow between components is outlined as follows: + +- The dApp frontend initiates a call to the Wallet Selector. +- The Wallet Selector then interacts with the Ethereum Wallet. +- The Ethereum Wallet communicates with the Transaction Relayer. +- The Transaction Relayer submits the transaction to the NEAR RPC. +- The NEAR protocol processes the transaction through the Wallet Contract. +- Finally, the Wallet Contract interacts with the dApp contract. + +Below are detailed examples, with implementation specifics provided subsequently. + +#### Example Transaction Flow: Incoming $NEAR Transfer + +- Alice, a NEAR compatible wallet user, controls the alice.near account on NEAR. +- Bob, an Ethereum compatible wallet user, controls the Ethereum address (EOA) `0xb794f5ea0ba39494ce839613fffba74279579268`. +- Alice directs her NEAR wallet to transfer 2 $NEAR to `0xb794f5ea0ba39494ce839613fffba74279579268`. +- On NEAR, an implicit account named `0xb794f5ea0ba39494ce839613fffba74279579268` is created, with a Wallet Contract deployed to it by the NEAR Protocol. +- Bob’s wallet periodically queries the `eth_getBalance` RPC method via the RPC-Translator. Once Alice’s transaction is confirmed on-chain, the RPC-Translator reports the balance of the implicit account, which is then displayed to Bob by his wallet. + +This process aligns with the user experience expectations of both NEAR and Ethereum users. + +#### Example Transaction Flow: Outgoing Function Call + +- Bob, using an Ethereum compatible wallet, controls the Ethereum address `0xb794f5ea0ba39494ce839613fffba74279579268`. +- DefiEx, a dApp on NEAR, consists of a web frontend and a smart contract at `defiex.near`. +- Bob uses DefiEx’s web frontend, which employs the **Wallet Selector** to connect his Ethereum compatible wallet. The frontend invokes the `signAndSendTransaction` method, typical in NEAR wallet interactions. +- Wallet Selector addon constructs an Ethereum transaction, which is then sent to Bob's wallet and signed. +- The Ethereum Wallet communicates this transaction to the **Transaction Relayer** via `eth_sendRawTransaction`. +- The Transaction Relayer validates the Ethereum transaction, converts it into a NEAR-compatible format, and sends it to Bob’s Wallet Contract at `0xb794f5ea0ba39494ce839613fffba74279579268`. +- The **Wallet Contract** decodes the Ethereum transaction, verifies the signature against the Ethereum address, and executes the corresponding action on the DefiEx smart contract. + +This method meets the expectations of both NEAR developers and Ethereum users. + +#### [COMPLEX] Example Transaction Flow: NEP-141 Transfer from Metamask + +- Charlie, a Metamask user, controls the Ethereum address `0xb794f5ea0ba39494ce839613fffba74279579268`. +- Declan, another Metamask user, controls the Ethereum address `0xf977814e90da44bfa03b6295a0616a897441acec`. +- Charlie, having acquired USDT on a centralized exchange, wishes to transfer 10 NEAR-native USDT to Declan’s address. +- Charlie adds NEAR-native USDT to Metamask, using an address derived from the `keccak-256` hash of the NEAR account `usdt.tether-token.near`. +- Metamask, via RPC Translator, displays USDT as a standard ERC20 token. +- Charlie initiates a transfer from Metamask to Declan. This is processed as a standard ERC20 `transfer` method call. +- The Transaction Relayer converts this into a NEAR transaction and sends it to the NEAR Blockchain. +- The Wallet Contract identifies this as a special ERC-20 transfer, queries the **Ethereum Translation Contract** for a corresponding NEAR contract, and constructs an action for the `usdt.tether-token.near` contract. + - First, it checks if Declan’s account is registered with USDT, funding the storage if necessary. + - Next, it processes the `ft_transfer` action, attaching `1 yoctoNEAR` as per [NEP-141](https://nomicon.io/Standards/Tokens/FungibleToken/Core). +- Post-transaction, the RPC Translator provides ERC-20 transaction logs to Metamask, confirming the transfer to Charlie. + +This transaction flow adheres to the expectations of Ethereum users. + +### Wallet Selector and Transaction Transformation + +Ethereum transactions, [RLP encoded](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/), encapsulate the following information: + +- `To` address of the transaction, +- `From` address (derived from the signature), +- `Gas price`, +- `Gas limit`, +- `Nonce`, +- Base token transfer amount within a transaction (`value`), +- `Chain ID`, +- `Data field`, +- `Signature` (yielding the public key and `From` address). + +For function calls to a smart contract, the data field contains: + +- The `Function Selector`, +- Function call parameters. + +Both `To` and `From` addresses, encoded in hexadecimal and prefixed with “0x”, comprise 20 bytes. The `From` address is the right-most 20 bytes of the **Keccak-256** hash of the binary public key of the transaction sender (an **EOA**, externally owned address). The To address signifies either the recipient EOA or an on-chain contract address. + +The `Function Selector` is the first 4 bytes of the **Keccak-256 hash** of the full function signature intended for the contract specified by the To address. For instance, the ERC-20 standard function `transfer(address _to, uint256 _value)` has the Function Selector `keccak-256("transfer(address,uint256)")[0,4]`, equal to `0xa9059cbb`. + +#### Ethereum Transaction Construction + +- Set the `chain ID` to a public constant (equal to [397](https://chainlist.org/chain/397) for mainnet and [398](https://chainlist.org/chain/398) for testnet). +- The `gas price`, fetched by the Ethereum Wallet from the RPC Translator (sourced from NEAR RPC), reflects the NEAR gas price. + - [COMPLEX]: Align Ethereum's gas consumption (usually in thousands or millions) with NEAR's TGas denomination. For instance, a 50k Ethereum gas consumption for ERC20 transfers aligns with 2-10 TGas in NEP-141 transfers. A **100,000x multiplier** is proposed for translating NEAR TGas to Ethereum gas. For example, a 10 TGas NEAR transaction would appear as 1M Ethereum Gas in an Ethereum wallet. Similarly, apply the inverse multiplier to gas prices. A typical NEAR gas price of `1e-4` $NEAR per TGas translates to `1e-9` $NEAR or `1 gwei` for Ethereum wallets, a familiar unit for Ethereum users. +- The `gas limit` is determined by the dApp-developer or through `eth_estimateGas` by the Ethereum Wallet, applying the aforementioned recalculation rules. +- The `nonce` and `signature` are managed by the Ethereum wallet, in line with Ethereum protocol. +- The `From` address adheres to Ethereum protocol too. + +#### Special Considerations for To and Data Field + +The `To` address and `data field` creation vary based on the dApp's input to the Wallet Selector: + +- **[COMPLEX]** If the `receiverID` matches `^0x[a-f0-9]{40}$` (indicating another Ethereum account), it's treated as an EOA and used as-is. This case is restricted to $NEAR transfers (excluding smart contract calls) and is integral to the **Ethereum standards simulation**. + - Note: **NEAR protocol will not host Ethereum smart contracts on Ethereum-style accounts** post-implementation of this proposal. +- Otherwise, the `receiverID` refers to a non-EOA account on NEAR. Here `keccak-256(receiverID)[12,32]` is used as the `To` address. + +For the `data field`: + +- When initiated by the Wallet Selector, function selectors and parameters mirror NEAR actions, encoded as native Ethereum types. For example: + - `FunctionCall(to: string, method: string, args: bytes, yoctoNear: uint32)` + - `Transfer(to: string, yoctoNear: uint32)` + - `Stake(public_key: bytes, yoctoNear: uint32)` + - `AddKey(public_key: bytes, nonce: uint64, is_full_access: bool, allowance: uint256, receiver_id: string, method_names: string[])` + - etc. +- **[COMPLEX]** The `yoctoNear` values are 32-bit, accommodating values under `1e6`. The total `yoctoNEAR` attached to a NEAR Action is `1e6 * + `, enabling: + - Accurate display of $NEAR balances in Ethereum wallets (assuming 18 decimals). + - Compatibility with NEAR standards like NEP-141, requiring 1 yoctoNEAR for ft_transfer and ft_transfer_call methods. +- **[COMPLEX]** If initiated by the Ethereum wallet (limited use cases like native or fungible token transfers), the data field is retained as-is. For instance, ERC-20 `transfer(to address, amount uint256)` calls map to NEAR actions in the Wallet Contract. + +### Wallet Contract + +The Wallet Contract is designed to process Ethereum transactions through the method `executeRLP(target: AccountId, rlp_transaction: Vec)`. The following steps outline its operation: + +1. **Parse the Transaction**: It starts by parsing the incoming Ethereum transaction. + +2. **Verify Target Address**: It checks if the `target` equals the transaction's `To` address, or if `keccak256(target)[12,32]` matches the `To` address. + +3. **Signature Verification and Extraction**: The contract verifies the signature to extract the `Public key` and `chainID`, ensuring the integrity of the transaction. + +4. **`From` Address Creation and Verification**: It generates the `From` address from the public key and confirms that it aligns with the `current_account_id` (the ID of the Wallet Contract). + +5. **`ChainID` Validation**: The contract validates that the `chainID` corresponds to the constant defined for NEAR. + +6. **`Nonce` Verification and Update**: It ensures the transaction nonce matches the stored nonce and then increments the stored nonce by one. + +7. **[COMPLEX] Value Calculation**: The contract sets the `Value` by multiplying the Ethereum transaction value by 1e6 and adding the `yoctoNear` value from the data field. It then confirms the attached deposit is either greater than or equal to this value or identifies it as a self-transaction (refer to **TR and Gas Payment** section for details). + +8. **[COMPLEX] ETC Lookup and Execution for Ethereum Transfers**: + + - If the `To` Address equals the `target` and the `value` is more than zero (indicating an Ethereum transfer), the Wallet Contract consults the ETC ("Ethereum Translation Contract") for the `To` address. + - If the ETC lacks an entry for the `To` address, it implies the recipient is an Ethereum EOA. In this case, the transaction is an ordinary transfer and should be executed as such. + - If the ETC contains an entry for the `To` address, indicating the recipient is a NEAR smart contract simulating an Ethereum standard (like NEP-141), the data field of the transaction is parsed against supported ERC standard calls to form the appropriate NEAR action. + +9. **NEAR Native Account Transfer**: If the data field is empty, it transfers the value to the target, typical for a $NEAR transfer to a NEAR-native account. Values below `1e6 yoctoNEAR` cannot be transferred. + +10. **Function Selector and Parameter Verification**: In cases where the data field is not empty, the contract verifies the function selector against matching NEAR actions. + +11. **Execution of NEAR Action**: After parameter verification, the Wallet Contract executes the corresponding NEAR action by creating a promise. + +These steps ensure that the Wallet Contract accurately processes and executes transactions, bridging the gap between Ethereum and NEAR protocols. + +### Transaction Relayer and Gas Payment + +The Transaction Relayer (TR) serves as an HTTP-JSONRPC endpoint compatible with Ethereum, primarily implementing the eth_sendRawTransaction method. Its validation process involves: + +- Ensuring correct encoding and signing of the transaction. +- Verifying the existence of the sender as an account on NEAR. +- Checking if the nonce is greater than the stored value in the Wallet Contract. + +Upon receiving a transaction, the TR assesses the `To` Address: + +- If it exists on-chain, the TR crafts a transaction with a FunctionCall to `executeRLP` on the `From` address account, setting `target` to the `To` Address. +- **[COMPLEX]** If the `To` Address is not on-chain, the TR consults the ETC (Ethereum Translation Contract) for the preimage of the `To` Address. If retrievable, it creates a FunctionCall to `executeRLP` on the `From` address account, directing `target` to the ETC result. + +#### Approaches to Gas Payment + +This project's challenge lies in appropriately assigning gas costs to the Ethereum-compatible account. Our proposed solutions are: + +1. **Simplified Gas Calculation**: By default, all transactions use the maximum gas limit, or a limit specified by the dApp developer, to bypass the complexity of gas amount computation. + +2. Gas Payment Scheme: + + - **Register the account with TR**. The Ethereum wallet sets up a `functionCall` key on its account, authorizing the `executeRLP` method call with a public key from the Transaction Relayer. This setup, compatible with the Transaction Translation model, employs the `AddKey` Action. Received transactions under this scheme are forwarded and paid for by the Transaction Relayer. Alternatively, the Wallet Contract could reimburse the Transaction Relayer via a `Transfer` promise. + - Once an Ethereum wallet is registered with the Transaction Relayer, this `functionCall` key is utilized for all subsequent transactions. Effectively, **the Transaction Relayer operates on the account's behalf, with the account bearing all gas costs.** + - To mitigate potential abuse by the Transaction Relayer, the Wallet Contract can revoke the `functionCall` key in cases of non-parseable transactions, invalid signatures, or nonce replay (subject to specific time and value deltas). This limitation restricts a dishonest Transaction Relayer to a single invalid transaction's NEAR gas cost (typically not exceeding 0.03 $NEAR under normal conditions). + +**[COMPLEX]**: This approach avoids unnecessary cross-contract calls, maintaining NEAR protocol interactivity for Ethereum users. + +**Optional Free Transactions**: Some relayers may offer a number of free transactions as an incentive for users to engage with NEAR. This can be achieved by the relayer's account directly calling the Wallet Contract's `executeRLP` function, instead of using the user’s account's `functionCall` access key. Some of these transactions may require attachment of $NEAR for covering storage staking or other requirements of NEAR protocol standards. + +### RPC Translator + +The RPC-Translator, functioning as an HTTP-JSONRPC endpoint compatible with Ethereum, implements a set of methods crucial for supporting Ethereum wallets. These include: + +- `eth_chainId`: Returns a constant value. +- `eth_gasPrice`: Fetches and recalculates respective data from NEAR RPC. +- `eth_estimateGas`: Returns a constant `30M`, aligned with the gas recalculation considerations previously mentioned. +- `eth_blockNumber`: Provides the current NEAR block height. +- `eth_getBalance`: Delivers the account's $NEAR balance, adjusted to Ethereum's decimal count (omitting the last 6 digits). +- `eth_getTransactionCount`: Retrieves the nonce value from the account's Wallet Contract. +- `eth_getTransactionByHash` and `eth_getTransactionReceipt`: Present transaction details by indexing the NEAR chain, with values recalculated for Ethereum's decimal count. +- `get_logs`: Offers log information from the NEAR chain, reformatted and recalculated for Ethereum compatibility. +- `eth_call`: Conducts a view call against NEAR RPC, translating parameters as per the **Ethereum standards simulation**. + +These methods enable Ethereum wallets to create transactions and access transaction status. The proposal also accommodates direct $NEAR and ERC20 transfers from Ethereum wallets. + +### [COMPLEX] Ethereum Standards Simulation and Ethereum Translation Contract + +To bridge the gap between NEAR's and Ethereum's differing addressing schemes, especially for interactions initiated directly from web3 wallets, the **Ethereum Translation Contract (ETC)** is pivotal. It maintains a simple mapping between Ethereum transaction hashes and corresponding NEAR account names: + +- `key`: `keccak256()[12,32]` +- `value`: `` + +The ETC provides two core functions: + +- `record(account_id: AccountId)`: Calculates the hash and records it in the map, requiring a deposit for storage staking. It is not applicable for Ethereum-style accounts. +- `lookup(hash: [u8; 32]) -> Option`: A view function that returns the associated NEAR account for a given hash, if available. + +NEAR accounts intending to interact with Ethereum wallets must register with the ETC. This registration is permissionless, allowing third-party on-the-fly registrations if necessary. + +It's important to note that ETC registration is not mandatory for most NEAR applications. For instance, applications like ref.finance, typically not called directly from Metamask, would route their contract calls through the frontend, thereby utilizing the Wallet Selector's transaction translation. + +In the initial phase, the focus will be on $NEAR token transfers and ERC-20 transfers, and approval management in the **Ethereum Standards Simulation**. Future expansions may include additional standards in the Wallet Contract (refer to the testing and upgrades section). The ETC itself does not require upgrades to support these enhancements. + +## Implementation Notes + +The proposed solution necessitates a protocol change for **deploying the Wallet Contract on implicit Ethereum accounts**. To facilitate this, we suggest integrating the Wallet Contract as a core feature of the NEAR protocol. This change would treat all Ethereum accounts as if they already have the Wallet Contract deployed. + +Additionally, to enhance security and align with Ethereum's operational flows, we propose prohibiting the deployment of other contracts on Ethereum accounts. This can be achieved by restricting Ethereum users from adding full access keys to these accounts, thereby significantly reducing the attack surface. + +## Testing and Upgrades + +Integrating the Wallet Contract as a protocol feature requires synchronized testing and upgrade processes between `nearcore` and the Wallet Contract. Fortunately, due to the absence of cross-dependencies, the Wallet Contract can be developed, maintained, and tested independently. Its latest stable version would then be incorporated into the `nearcore` Testnet release, followed by integration into the Mainnet release. + +We recommend that any modifications to the Wallet Contract's functionality, such as adding support for new Ethereum standards over time, should be incorporated into the NEAR enhancement process. This approach ensures a structured and systematic update mechanism. + +The development and testing of off-chain components, like the RPC-Translator, will precede those of on-chain components. This sequential approach allows for thorough testing and refinement of each component before integration into the larger system. + +## Limitations and Risks + +- **[COMPLEX] Dependence on Ethereum Standards Simulation**: The solution heavily depends on simulating Ethereum standards in the Wallet Contract and RPC-Translator. While standards like ERC20 are manageable, others may be too complex or impossible to emulate accurately. + +- **[COMPLEX] Ambiguity in Transaction Conversion**: The emulation of Ethereum standards may lead to confusion in indexing or displaying transactions due to the dual paths of NEP-141 transfer encoding – either through standard conversion via Wallet Selector or originating directly from the wallet. This does not introduce new attack vectors. Users in general should exercise caution and avoid transactions with unfamiliar contracts or frontends. + +- **RPC-Translator Limitations**: The RPC-Translator is tailored for wallet interactions and simple chain functions, but it's not equipped for advanced use cases requiring complete block data. Extending its capabilities could be challenging and resource-intensive. + +- **[COMPLEX] Challenges with the Ethereum Translation Contract (ETC)**: The ETC, vital for integrating NEAR accounts with Ethereum wallets, adds complexity and can lead to user experience issues if registration is overlooked. Automating ETC population through indexing services could mitigate this risk. Future developments might explore on-chain contract lists and function signatures for introspection. + +- **Power and Opacity of Wallet Contract**: The Wallet Contract, pivotal for executing NEAR Actions, may be obscure to Ethereum Wallet users. This necessitates stringent checks and limitations on action parameters, as noted in the proposal to restrict full access key additions. + +- **Lack of Batch Transaction Support**: The proposal currently does not accommodate batch transactions available in Wallet Selector, primarily due to limited utility and the complexity it would introduce, along with associated security concerns. + +- **[COMPLEX] Potential for inclusion NEAR account functionality in Wallet Contract**: An expanded version of the Wallet Contract, which includes NEAR account functionality, could retain valuable NEAR user patterns. For example, allowing using BOS frontend functionCall keys for Ethereum accounts. This would facilitate simple actions without needing to sign each transaction in the Ethereum wallet. While promising, this approach requires careful management. + +- **Wallet Contract Upgrades**: Positioning the Wallet Contract as a protocol feature could limit its upgradability and inadvertently enable smart contract deployments with unbilled storage allocation. Careful implementation can mitigate potential storage growth on NEAR. + +- **Exclusion of Native Ethereum Contract Deployment on NEAR**: The proposal does not address the deployment of Ethereum contracts natively on NEAR. Although this is possible via the Aurora network, interactions between NEAR-onboarded Ethereum users and Aurora contracts would necessitate additional steps, like asset bridging or using the [Aurora XCC SDK](https://dev.aurora.dev/posts/cross-ecosystem-communication). + +## Future Opportunities + +- **Expansion of Ethereum Standards**: A key future development involves simulating other Ethereum standards such as ERC-721, ERC-1155, or ERC-3643. This would enhance NEAR's frontend compatibility with various Ethereum use cases. +- **Account Abstraction and Extended Features**: This proposal lays the groundwork for account abstraction, potentially leading to the introduction of advanced features in the Wallet Contract. These could include native support for multi-signatures, time-locks, social recovery, and alternative signature algorithms compatible with secure elements in widespread devices. +- **Aurora Integration**: Exploring integration with Aurora to enable interactions with Aurora-hosted contracts through NEAR, utilizing Ethereum transaction formats and processes. +- **Bridging and Oracle Onboarding**: This model could facilitate simplified bridging and oracle integration, contributing to the expansion of NEAR's infrastructure. + +## Scope of the Project + +The scope of this project is extensive, encompassing several critical components: + +1. Core Technology: + + - **Wallet Contract**: A crucial, security-sensitive component requiring detailed audits and testing. + - **`nearcore` Protocol Upgrade**: Modification to treat Ethereum-style accounts as implicit and deploy the Wallet Contract on them. + - **Wallet Selector Add-Ons**: Ensuring compatibility with Metamask and WalletConnect-compatible wallets. + - **Transaction Relayer and RPC Translator**: Key elements of the NEAR Web3 RPC middleware, working alongside the NEAR node. + - **Ethereum Translation Contract (ETC)**: A simpler component in comparison to others, yet vital for the system. + +2. **Integration Testing**: Given the solution's distributed nature, comprehensive integration testing is imperative. + +3. **Documentation Development**: Detailed documentation is necessary, enabling third-party developers to understand and potentially replicate parts of the system, except for the Wallet Contract. + +4. **Node Operators Awareness and Public Infrastructure**: Launching and maintaining the NEAR Web3 RPC as a public service, similar to the existing NEAR RPC, and informing third-party node operators about the update and maintenance protocols. + +5. **Integration with Key Platforms**: For effective Ethereum user engagement, integration with the following is essential: + + - **Centralized Exchanges**: Permitting withdrawals to Ethereum-style addresses. + - **Bridges**: Facilitating login on the NEAR side with Ethereum-compatible wallets. + - **NEAR-native Projects**: Updating Wallet Selector configurations to support Ethereum-compatible wallet logins. Anticipated challenges include wallet address display issues, requiring adjustments. + - **Products to allow for key NEAR Wallet functionality**. Allowing Ethereum users to exercise core features of the NEAR protocol in a dApp: staking, key management, work with lockup contracts, etc. These may be implemented as BOS components. + +6. **Bug Bounty Program**: Establishing a program to address potential vulnerabilities, especially for on-chain components like the Wallet Contract and ETC. + +7. **Ongoing Development and Bug Fixes**: The project's complexity necessitates a proactive approach to bug fixes and future enhancements. + +## Reference implementation + +The protocol changes necessary for the project include: + +- Creating Ethereum-like (0x) implicit accounts using `Transfer` action, +- Automatically deploying the wallet contract to those 0x implicit accounts. + +These protocol changes are implemented in nearcore ([eth-implicit accounts PR 10224](https://github.com/near/nearcore/pull/10224), [wallet contract implementation](https://github.com/near/nearcore/tree/1ab9b42c3d723604a214e685d8ed39f7d6434ae2/runtime/near-wallet-contract/implementation)) and have been stabilized in protocol version 70 ([PR 11765](https://github.com/near/nearcore/pull/11765)).