🚧 This EIP had no activity for at least 6 months.

EIP-2525: ENSLogin Source

AuthorHadrien Croubois
TypeStandards Track
Requires 137, 634, 1193, 2304

1. Abstract

This presents a method to improve a universal method of login to the ethereum blockchain, leveraging the metadata storage provided by the ENS. We consider a user to be logged in when we have an EIP-1193 provider that can sign transaction and messages on his behalf. This method is inspired by Alex Van de Sande’s work and Web3Connect. In the future, the approach described here-after should be extended to work with any blockchain.

2. Motivation

Multiple wallet solutions can be used to interact with the Ethereum blockchain. Some (metamask, gnosis, …) are compatible as they inject a standardized wallet object in the browser without requiring any effort from the Dapp developers, but they require an effort on the user side (user has to install the plugin). Other solutions (Portis, Authereum, Torus, Universal Login, …) propose a more seamless flow to non-crypto-aware users but require an integration effort from the Dapp developers. Hardware wallet (ledger, trezor, keepkey, …) also require integration effort from the Dapp developers.

When Dapps integrate login with multiple solutions, they rely on the user choosing the correct wallet-provider. This could prove increasingly difficult as the number of wallet-provider increases, particularly for novice users. Additionally, if decentralized applications pick and choose only a handful of wallets to support, the current incumbent wallets will have a distinct advantage and new wallets will struggle to find adoption. This will create a less competitive environment and stifle innovation. Rather than relying on the user choosing which wallet-provider to connect with (as does Web3Connect), ENSLogin proposes to use user-owned ENS domain as entry points. Metadata attached to these ENS domains is used to detect which wallet-provider if used by the corresponding account.

That way, ENSLogin would allow any user to connect to any Dapp with any wallet, using a simple domain as a login.

3. Description

3.1. Overview

The ENSLogin works as follow:

  • Request an ENS domain from the user
  • Resolve the ENS domain to retrieve (see EIP-137)
  • Interpret the text entry and download the file it points to
  • Evaluate the content of the downloaded file
  • Return the corresponding object to the Dapp

At this point, the app should process like with any web3 provider. Calling the enable() functions should ask the users for wallet specific credentials is needed.

This workflow is to be implemented by an SDK that Dapp could easily import. The SDK would contain the resolution mechanism and support for both centralized and decentralized storage solution. Wallet-provider specific code should NOT be part of SDK. Wallet-provider specific code should only be present in the external file used to generate the web3 provider.

3.2. Details

  • Text entry resolution: A pointer to the code needed to instantiate the wallet-provider is recorded using the ENS support for text entries (see EIP-634). The corresponding key is enslogin (subject to change). If no value is associated with the key enslogin at the targeted domain, we fallback to metadata store on the parent’s node with the key enslogin-default (subject to change). Example: for the ens domain username.domain.eth, the resolution would look for (in order):
    • resolver.at(ens.owner(nodehash("username.domain.eth"))).text(nodehash("username.domain.eth"), 'enslogin')
    • resolver.at(ens.owner(nodehash("domain.eth"))).text(nodehash("domain.eth"), 'enslogin-default')
  • Provider link: Code for instantiating the wallet-provider must be pointed to in a standardized manner. This is yet not specified. The current approach uses a human-readable format scheme://path such as:

    • ipfs://Qm12345678901234567890123456789012345678901234
    • https://server.com/enslogin-module-someprovider

    And adds a suffix depending on the targeted blockchain type (see SLIP 44) and language. Canonical case is a webapp using ethereum so the target would be:

    • ipfs://Qm12345678901234567890123456789012345678901234/60/js
    • https://server.com/enslogin-module-someprovider/60/js

    Note that this suffix mechanism is compatible with http/https as well as IPFS. It is a constraint on the storage layer as some may not be able to do this kind of resolution.

  • Provider instantiation:
    • [JAVASCRIPT/ETHEREUM] The file containing the wallet-provider’s code should inject a function global.provider: (config) => Promise<web3provider> that returns a promise to a standardized provider object. For EVM blockchains, the object should follow EIP-1193.
    • Other blockchain types/langages should be detailed in the future.
  • Configuration object: In addition to the username (ENS domain), the Dapp should have the ability to pass a configuration object that could be used by the wallet-provider instantiating function. This configuration should include:
    • A body (common to all provider) that specify details about the targeted chain (network name / node, address of the ens entrypoint …). If any of these are missing, a fallback can be used (mainnet as a default network, bootstrapping an in-browser IPFS node, …).
    • Wallet provider-specific fields (optional, starting with one underscore _) can be added to pass additional, wallet-provider specific, parameters / debugging flags.
    • SDK specific fields (optional, starting with two underscores __) can be used to pass additional arguments.

    Minimal configuration:

          provider: {
              network: 'goerli'

    Example of advanced configuration object:

          provider: {
              network: 'goerli',
              ens:     '0x112234455c3a32fd11230c42e7bccd4a84e02010'
          ipfs: {
              host: 'ipfs.infura.io',
              port: 5001,
              protocol: 'https'
          _authereum: {...},
          _portis: {...},
          _unilogin: {...},
          _torus: {...},
          __callbacks: {
              resolved: (username, addr, descr) => {
                  console.log(`[CALLBACKS] resolved: ${username} ${addr} ${descr}`);
              loading: (protocol, path) => {
                  console.log(`[CALLBACKS] loading: ${protocol} ${path}`);
              loaded: (protocol, path) => {
                  console.log(`[CALLBACKS] loaded: ${protocol} ${path}`);

TODO (maybe move that part to section 6.1): Add SLIP 44 compliant blockchain description to the config for better multichain support. This will require a additional field ENS network to know which ethereum network to use for resolution when the targeted blockchain/network is not ethereum (could also be used for cross chain resolution on ethereum, for example xDAI login with metadata stored on mainnet)

3.3. Decentralization

Unlike solution like Web3Connect, ENSLogin proposes a modular approach that is decentralized by nature. The code needed for a Dapp to use ENSLogin (hereafter referred to as the SDK) only contains lookup mechanism for the ethereum blockchain and the data storages solutions. The solution is limited by the protocols (https / ipfs / …) that the SDK can interact with. Beyond that, any wallet-provider that follows the expected structure and that is available through one of the supported protocol is automatically compatible with all the Dapps proposing ENSLogin support. There is no need to go through a centralized approval process. Furthermore, deployed SDK do not need to be upgraded to benefit from the latest wallet updates. The only permissioned part of the protocol is in the ENS control of the users over the metadata that describes their wallet-provider implementation. Users could also rely on the fallback mechanism to have the wallet-provider update it for them.

3.4. Incentives

We believe ENSLogin’s biggest strength is the fact that it aligns the incentives of Dapp developers and wallet-providers to follow this standard.

  • A wallet-provider that implements the required file and make them available will ensure the compatibility of its wallet with all Dapps using ENSLogin. This will remove the burden of asking all Dapps to integrate their solutions, which Dapps are unlikely to do until the wallet as strong userbase. Consequently, ENSLogin will improve the competition between wallet-providers and encourage innovation in that space
  • A Dapp that uses ENSLogin protocol, either by including the ENSLogin’s SDK or by implementing compatible behaviour, will make itself available to all the users of all the compatible wallet. At some point, being compatible with ENSLogin will be the easiest to reach a large user-base.
  • ENSLogin should be mostly transparent for the users. Most wallet provider will set up the necessary entries without requiring any effort from the user. Advanced users can take control over the wallet resolution process, which will be simple once the right tooling is available.

3.5. Drawbacks

While ENSLogin allows dapps to support any wallet for logging in, dapps still must choose which wallets they suggest to users for registration. This can be done through a component like Web3Connect or BlockNative’s

4. Prototype


5. Support by the community

5.1. Adoption

Name Live Module Assigns ENS names support by default
Argent yes no yes no
Authereum yes yes yes no
Fortmatic yes no no no
Gnosis Safe yes yes* no no
Ledger yes beta no no
KeepKey yes no no no
Metamask yes yes no no
Opera yes yes* no no
Portis yes yes no no
SquareLink yes no no no
Shipl no no no no
Torus yes yes no no
Trezor yes no no no
UniLogin beta beta yes no

*use the metamask module

6. Possible evolutions

6.1. Multichain support


7. FAQ

7.1. Can anyone connect with my login? Where are my private keys stored?

ENSLogin only has access to what is recorded on the ENS, namely your address and the provider you use. Private key management is a is handled by the provider and is outside ENSLogin’s scope. Some might store the key on disk. Other might rely on custodial keys stored on a remote (hopefully secure) server. Others might use a dedicated hardware component to handle signature and never directly have access to the private key.

7.2. How do I get an ENS Login?

TODO (this might need a separate ERC)


Please cite this document as:

Hadrien Croubois, "EIP-2525: ENSLogin," Ethereum Improvement Proposals, no. 2525, February 2020. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-2525.