SEP-43 extension, Wallet Provider Discovery

[aristidesstaffieri]

Problem

SEP-43 standardizes what an application can ask a wallet to do. It does not standardize how it finds the wallet. Every wallet is discovered through a wallet-specific side channel, which requires projects like Stellar Wallets Kit to implement bespoke modules per wallet in order to account for the differences.

Examples of pain points/work-arounds

• Freighter Mobile injects window.stellar = { provider: "freighter", platform: "mobile", version } and a User-Agent marker so libraries can tell they are running inside it (freighter-mobile #314). This gets special cased in Stellar Wallets Kit by making FreighterModule.isAvailable() return false and WalletConnectModule.isPlatformWrapper() return true from a hardcoded list of providers. Sites that never configured WalletConnect show "Install Freighter" inside Freighter Mobile.
• freighter-mobile #1001 aims to replace the WalletConnect round trip with a bridge injected into the WebView. It defines it's own transport and ships it's own sdk relying on the window.stellar global, which is open to collisions from any other script.
• Stellar-Wallets-Kit #111 proposes different ways to give a host with browser control a way to provide wallet interactions. Today the only option is to impersonate the scheme from an existing provider.

Proposal

A new SEP or an extension to SEP-43 which defines discovery for wallets.
Similarly to EIP-6963, we can use window events for announcement.

• stellar:announceProvider for wallets to announce they are ready to connect, or in response to a stellar:requestProvider from the page.
• A standard event detail for SEP-43, { info, provider } where info carries metadata like a session identifier and provider identifier.

How it resolves the problem cases

• for mobile wallets: they can make a platform specific announcement, like { rdns: "app.freighter", platform: "mobile", wrapsPage: true } and wrapsPage maps to the existing pattern in Stellar Wallets Kit of the isPlatformWrapper flag. This gets rid of the hard-coded checks and any future mobile wallet can use this pattern without a change to the Stellar Wallets Kit.
• in-app WebView providers: this can announce a SEP-43 provider instead of relying on the global window.stellar object. No need for the sdk or coordination on the global interface.
• Agent hosts: they can inject the announcer as an init script, using a platform identifier like agent or external, the signing can stay on the agent side and Stellar Wallets Kit needs no special agent mode.

Alternatives

Standardize window.stellar: fixes some of the issues but is still subject to clashes.
User-Agent sniffing: requires additions for every new wallet and provider type.
Keep maintaining a layer, like Stellar Wallets Kit, that absorbs the differences between providers. This required changes for every new wallet and provider.

[earrietadev]

This has been mentioned a couple of times in the Discord server (how to discover available wallets). My answer has always been that thinking it that way only accounts for wallets that have access to the website you are visiting, which includes: mobile wallets opening the site within in-app browsers and browser extensions... while leaving out all the wallets that don't follow that logic: browser-based wallets (getting more traction thanks to passkeys) hardware wallets and bridge-based wallets like WalletConnect. So at the end of the day we will still need to handle multiple ways to know if a wallet is available or not, without matter if this is adopted by everybody.

That being said, I think it's still valuable to extend SEP-43 with this so we expect the same behavior from most of the wallets on the network.

One quick thing about your first pain point: this only happens because Freighter uses two separate ways to talk with a site based on the nature of the wallet, for example, if you're using the site from the wallet, it won't matter whether this is implemented or not because if the site has not configured WalletConnect, it will just be incompatible with Freighter. It's the same for Lobstr but not for xBull, because xBull with the same module handles if is being used form a mobile phone, from the web version or from the extension. If we want to remove that pain point from the Freighter experience, we need to do what stellar/freighter-mobile#1001 is suggesting, but I wouldn't put the SDK in the window.stellar even if in theory it shouldn't have any issue (that way we don't encourage devs to use it to place logic in that object).

Regarding window.stellar, IMO that should only be used when the wallet itself is opening the site. Otherwise, it will be the same issue ETH had for years, where it was always a race between installed wallets in the browser to see who got it. That's why the wallets kit only uses it to know if the site is being opened within a wallet (a site opened from a wallet will never see the window.stellar clash with something else).

[aristidesstaffieri]

Yeah this makes sense, I think freighter-mobile #1001 and the SEP extension are complementary so that the bridge can be exposed through an announced provider. It definitely doesn't solve it for every wallet type like you mentioned but it does improve the detection code. A bunch of the modules in Stellar Wallets Kit implement their own version of "is this wallets global available?" so they could just re-use the announcement module if it existed. It should also help remove the isAvailable timing code that can result in timing bugs that show the wallet as not installed, since the announcement is push based.