From 005604075522f9c5a6f8f0e3968274a46d469e97 Mon Sep 17 00:00:00 2001 From: Jerry Musaga Date: Thu, 30 Jul 2026 02:49:27 +0100 Subject: [PATCH] docs(wallet): document multi-wallet flow and remove dead FreighterAdapter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit xBull (and Lobstr/Hana/Rabet) desktop support already works end-to-end via Stellar Wallets Kit — no per-provider code was missing. This just removes the unused back-compat FreighterAdapter (superseded by StellarWalletAdapter) and documents the current provider-agnostic connect/sign flow, including xBull's desktop behavior. Closes #74 --- docs/architecture.md | 31 ++++++++++++++++++++--- src/wallet/FreighterAdapter.ts | 46 ---------------------------------- src/wallet/index.ts | 6 ++--- 3 files changed, 31 insertions(+), 52 deletions(-) delete mode 100644 src/wallet/FreighterAdapter.ts diff --git a/docs/architecture.md b/docs/architecture.md index e4db930..8865342 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -11,9 +11,11 @@ Browser (React) └── Stellar Testnet — three Soroban smart contracts ``` -Authentication is **wallet-based** (Freighter/Albedo): the connected Stellar address is -stored in `localStorage.vinculo_wallet` and gates the routes. There is no separate auth -backend or user database. +Authentication is **wallet-based**: the connected Stellar address is stored in +`localStorage.vinculo_wallet` and gates the routes. There is no separate auth backend or +user database. Connection and signing go through Stellar Wallets Kit (see +[Wallet providers](#wallet-providers) below), which supports Freighter, xBull, Lobstr, +Hana and Rabet on desktop, and Albedo on mobile. --- @@ -73,6 +75,29 @@ In-memory React context. Tracks deposits, withdrawals, stakes, and credit state |---|---| | `useWallet` | Reads `vinculo_wallet` from localStorage, provides `shortWallet`, `walletMismatch` and `disconnect` | +### Wallet providers (`src/lib/stellarWalletsKit.ts`, `src/wallet/`) + +Connect and sign both go through **Stellar Wallets Kit**, which owns its own +provider-selection modal (`kit.authModal()`). App code never branches on which wallet was +chosen — `connectWallet()` / `signTransactionXdr()` in `mobileWalletConnectors.ts` are +provider-agnostic, and `StellarWalletAdapter` (the `WalletAdapter` implementation used +throughout the app) simply delegates to them. Adding a new provider is a matter of +registering its module in `stellarWalletsKit.ts` — no other files need to change. + +Registered modules: `FreighterModule`, `AlbedoModule`, `xBullModule`, `LobstrModule`, +`HanaModule`, `RabetModule`. + +| Environment | Providers | Notes | +|---|---|---| +| Desktop | Freighter, xBull, Lobstr, Hana, Rabet | User picks one from the kit's modal; the choice is persisted (`vinculo_wallet_provider`) and restored on reload. | +| Mobile | Albedo | Selected automatically; also reachable via Privy for email login (see `privyBridge.ts`). | + +**xBull on desktop:** connect and sign follow the same path as every other desktop +provider above — no xBull-specific code exists or is needed. `useWallet`'s Freighter +"extension gone" polling (`src/hooks/useWallet.tsx`) only applies when `provider === +FREIGHTER_ID`; other providers, including xBull, are not polled for availability and rely +on the kit surfacing connection/signing errors directly. + --- ## Layer 2 — Serverless API diff --git a/src/wallet/FreighterAdapter.ts b/src/wallet/FreighterAdapter.ts deleted file mode 100644 index 3d99dbc..0000000 --- a/src/wallet/FreighterAdapter.ts +++ /dev/null @@ -1,46 +0,0 @@ -import * as FreighterAPI from "@stellar/freighter-api"; -import type { WalletAdapter } from "./WalletAdapter"; - -const STORAGE_KEY = "vinculo_wallet"; - -/** - * FreighterAdapter — WalletAdapter implementation backed by the - * Freighter browser extension (@stellar/freighter-api). - */ -export class FreighterAdapter implements WalletAdapter { - async isConnected(): Promise { - try { - const result = await FreighterAPI.isConnected(); - // freighter-api v4 returns { isConnected: boolean } - return typeof result === "object" ? result.isConnected : Boolean(result); - } catch { - return false; - } - } - - async connect(): Promise { - const response = await FreighterAPI.requestAccess(); - if (response.error) throw new Error(response.error); - if (!response.address) throw new Error("No se obtuvo la dirección de la wallet."); - localStorage.setItem(STORAGE_KEY, response.address); - return response.address; - } - - async sign(xdr: string, networkPassphrase: string): Promise { - const result = await FreighterAPI.signTransaction(xdr, { networkPassphrase }); - if (result.error || !result.signedTxXdr) { - throw new Error(result.error || "Firma rechazada."); - } - return result.signedTxXdr; - } - - disconnect(): void { - localStorage.removeItem(STORAGE_KEY); - localStorage.removeItem("vinculo_onboarded"); - window.location.href = "/login"; - } - - getAddress(): string | null { - return localStorage.getItem(STORAGE_KEY); - } -} diff --git a/src/wallet/index.ts b/src/wallet/index.ts index b4bae8f..f6dd5bc 100644 --- a/src/wallet/index.ts +++ b/src/wallet/index.ts @@ -1,12 +1,12 @@ export type { WalletAdapter } from "./WalletAdapter"; -export { FreighterAdapter } from "./FreighterAdapter"; // kept for back-compat export { StellarWalletAdapter } from "./StellarWalletAdapter"; import { StellarWalletAdapter } from "./StellarWalletAdapter"; /** * Singleton adapter used throughout the app. - * Backed by StellarWalletAdapter which auto-selects Freighter (desktop) - * or Albedo (mobile) via mobileWalletConnectors. + * Backed by StellarWalletAdapter, which delegates to Stellar Wallets Kit + * (see src/lib/stellarWalletsKit.ts) for both desktop (Freighter, xBull, + * Lobstr, Hana, Rabet) and mobile (Albedo) providers via its selection modal. */ export const walletAdapter = new StellarWalletAdapter();