ERC-7555 Single sign-on for account discovery

Draft · Accounts & wallets · created 2023-11-10

Defines a single sign-on (SSO) scheme that lets multiple apps consistently discover and use accounts created with methods that don't use Ethereum's standard signing key (secp256k1), such as passkeys.

Why it is needed

Security hardware such as passkeys or YubiKeys generates a different key pair for each domain (website address). So if mobile app A and web app B each integrate passkey login, the same user ends up with a different key and a different address in each app. This is a major obstacle for users who expect to get the same address everywhere, as they would with a hardware wallet. The problem grows as smart accounts (ERC-4337) become more widespread. An app has no way to know whether a user already has a smart account created elsewhere, so it ends up deploying yet another new account under its own domain. As a result, a single user ends up with multiple unconnected accounts, and assets become fragmented with no way to consolidate them. This standard aims to solve this problem by defining a common way for apps to look up a user's signing address and existing smart account.

In depth

Background: per-domain key pairs and ERC-4337

Before ERC-4337, using a smart contract account required a valid signature from a secp256k1 key pair. After 4337, alternative signing methods such as passkeys, YubiKeys, and the secure enclaves on iOS and Android gained popularity; these don't follow the secp256k1 curve and require a paymaster to submit transactions. Because each provider uses a different key-generation approach, such as Shamir's Secret Sharing, MPC, or secure enclaves, there is no unified way to reproduce the same EOA address or smart account address across multiple apps using alternative signing methods. In particular, since passkeys and YubiKeys generate a unique key pair per domain, an app that embeds authentication directly can never recover a unified key pair.

Goals and non-goals

This standard aims to achieve three things: a standard way for apps to request a user's signing address, a standard way to provide single sign-on (SSO) for alternative signing methods, and a standard way for apps to expose smart accounts created through their own service. Conversely, it does not address how users sign messages across domains, how providers generate key pairs, or how apps handle their user interface logic.

Redirect structure and the two routes

The app must move the user to the provider's URI following the defined URI request syntax, and must implement a valid callback redirect URI to receive the response. There are two routes. /auth/ is the route that authenticates the user and requests credentials. /sendTransaction/ is the route for sending the transaction payload the user is to sign; it is a convenience feature that handles authentication and plugin registration together in a single redirect instead of two.

Request and response of the auth route

The request takes the form https://<PROVIDER_URI>/auth/?redirect_uri=<YOUR_REDIRECT_URI>&chain_id=<CHAIN_ID>. redirect_uri is the address the provider returns to, and chain_id is the chain ID of the target network. The response comes back to the app's redirect_uri with a smart_account_address query attached, and this value must be returned in CAIP-10 format as the on-chain address of the smart account.

Request and response of the sendTransaction route

The request takes a transaction parameter in addition to redirect_uri and chain_id. transaction is the RLP-encoded transaction that needs a signature. The response returns smart_account_address along with tx_hash, the transaction hash, as query parameters. This route is used by apps that want to handle authentication and transaction signing in a single redirect.

Design rationale: borrowing from web SSO

Inspired by how unified login works on today's web, it uses a simple redirect pattern made up of requests and responses. The app only passes callback URL information, so that the provider's website does not need to store state or depend on web requests. The provider authenticates the user by parsing the redirect URL, and the authentication method itself can be anything as long as it produces a valid public address and can recover the smart account deployed through the provider. The reference implementation notes that whether to use location.replace() or location.href is up to the experience the app wants to provide.

Proposal status: Draft

This proposal is still in Draft status. The security considerations section still carries a note that further discussion is needed, so the content may change or progress may stall.

Things to watch out for

Original ERC · ← ERCs