EIP-7039: Scheme-Handler Discovery Option for Wallets Ethereum Improvement Proposals AllCoreNetworkingInterfaceERCMetaInformational ⚠️ Draft Standards Track: Interface EIP-7039: Scheme-Handler Discovery Option for Wallets Using custom protocol handlers to initiate connections between web pages and wallets. Authors Sam Wilson (@SamWilsn) Created 2023-05-15 Discussion Link https://ethereum-magicians.org/t/shadow-a-scheme-handler-discovery-option-for-wallets/14330 Requires EIP-1193 Table of Contents Abstract Motivation Specification Initiating a Connection Communicating on an Established Connection Icon Images Rationale Backwards Compatibility Security Considerations Copyright Abstract This proposal (affectionately known as SHADOW) is an alternative to EIP-1193 for wallet discovery in web browsers that requires no special permissions. Web pages intending to open a connection to a wallet inject an iframe tag pointing at a well-known scheme. Communication between the page and the wallet uses the postMessage API. Motivation Current wallet discovery methods (eg. window.ethereum) only support one active wallet at a time, and require browser extensions to request broad permissions to modify web pages. Ideally users should be able to have multiple wallets active, and choose between them at runtime. This not only results in an improved user experience but also reduces the barrier to entry for new browser extensions as users are no longer forced to only install one browser extension at a time. With SHADOW, and unlike other recent proposals, browser extensions do not need blanket content_scripts or any permissions at all. Furthermore, any web page (and not just browser extensions) can register a handler for a protocol. That means better support for pure web wallets, native executable wallets, and hardware wallets. As long as a wallet can serve a page securely, it can register itself as a handler. Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174. Initiating a Connection To initiate a connection to a provider, a web page SHOULD: Add an event listener to window for the "message" event (or set window.onmessage.) Create an iframe tag with a src attribute value of web+evm://; then Attach the iframe to the DOM. Wait for a "message" event with a non-nullish source equal to the iframe’s contentWindow. Save the first port from the message event for further communication. This is referred to as the “primary port.” The event received in step 3 MAY contain additional information about the provider. If present, the event data SHALL satisfy the following TypeScript interface: interface ProviderInfo { name: string; icon: string; } Where: name is the human-readable name of the provider; and icon is a URI pointing at an image. See Icon Images. Communicating on an Established Connection The web page and wallet MAY make requests of the other. The party making the request is known as the requester, and the replying party is known as the responder. A requester MAY make requests of the responder by sending a message (using postMessage) on the primary port. The message MAY include a MessagePort as the first item of the message’s transfer list to receive a reply. This port is known as a “reply port.” The message’s data MUST satisfy EIP-1193’s RequestArguments interface, and SHALL be interpreted as described there. The responder SHALL respond by posting a single message to the reply port, if a reply port was transferred. The message’s data SHALL satisfy the following TypeScript interface, where ProviderRpcError is defined in EIP-1193: interface Response { result?: unknown; error?: ProviderRpcError; } Exactly one of result or error SHALL be present on the response. If present, result SHALL be equivalent to the result field of the named JSON-RPC method’s response. Error objects SHOULD follow the recommendations set out in EIP-1193. A request without a transferred reply port SHALL NOT be considered an error, even if a reply would have been sent. Icon Images Rationale Instead of directly using the iframe.contentWindow’s message port, SHADOW transfers a message port in the first message. This allows the iframe, in some specific scenarios, to completely hand off communication, so the web page and the provider communicate directly, without any proxying in the iframe. Backwards Compatibility While not backwards compatible with EIP-1193, this proposal uses extremely similar data structures to make the transition as painless as possible. It is possible to implement an EIP-1193 compatible provider using this proposal like so: Security Considerations Both providers and web pages MUST verify the origin of messages before trusting them. Copyright Copyright and related rights waived via CC0. Citation Please cite this document as: Sam Wilson (@SamWilsn), "EIP-7039: Scheme-Handler Discovery Option for Wallets [DRAFT]," Ethereum Improvement Proposals, no. 7039, May 2023. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7039. Ethereum Improvement Proposals Ethereum Improvement Proposals ethereum/EIPs Ethereum Improvement Proposals (EIPs) describe standards for the Ethereum platform, including core protocol specifications, client APIs, and contract standards.