@satoshai/kit 0.3.1 → 0.4.1

package/README.md

@@ -23,7 +23,7 @@ pnpm add @satoshai/kit @stacks/transactions react react-dom
 ## Quick Start
 
 ```tsx
-import { StacksWalletProvider, useConnect, useWallets, useAddress, useDisconnect } from '@satoshai/kit';
+import { StacksWalletProvider, useConnect, useAddress, useDisconnect } from '@satoshai/kit';
 
 function App() {
   return (
@@ -35,7 +35,6 @@ function App() {
 
 function Wallet() {
   const { connect, reset, isPending } = useConnect();
-  const { wallets } = useWallets();
   const { address, isConnected } = useAddress();
   const { disconnect } = useDisconnect();
 
@@ -51,11 +50,7 @@ function Wallet() {
   return (
     <div>
       {isPending && <button onClick={reset}>Cancel</button>}
-      {wallets.map(({ id, available }) => (
-        <button key={id} onClick={() => connect(id)} disabled={!available || isPending}>
-          {id}
-        </button>
-      ))}
+      <button onClick={() => connect()} disabled={isPending}>Connect Wallet</button>
     </div>
   );
 }
@@ -70,6 +65,7 @@ Wrap your app to provide wallet context to all hooks.
 ```tsx
 <StacksWalletProvider
   wallets={['xverse', 'leather', 'wallet-connect']}  // optional — defaults to all supported
+  connectModal={true}                                  // optional — defaults to true
   walletConnect={{ projectId: '...' }}                 // optional — enables WalletConnect
   onConnect={(provider, address) => {}}                // optional
   onAddressChange={(newAddress) => {}}                 // optional — Xverse account switching
@@ -83,11 +79,38 @@ Wrap your app to provide wallet context to all hooks.
 
 > **Important:** Define `wallets` and `walletConnect` outside of your component (or memoize them) so they remain referentially stable across renders. These values are treated as static configuration.
 
+#### `connectModal` (default: `true`)
+
+Controls whether `connect()` with no arguments shows `@stacks/connect`'s built-in wallet selection modal.
+
+```tsx
+// Default — modal handles wallet selection
+<StacksWalletProvider>
+  <App /> {/* connect() opens the modal */}
+</StacksWalletProvider>
+
+// Headless — manage wallet selection yourself (wagmi-style)
+<StacksWalletProvider connectModal={false}>
+  <App /> {/* connect('xverse') only, connect() with no args is a no-op */}
+</StacksWalletProvider>
+```
+
+When `connectModal` is enabled:
+- `connect()` with no args opens the `@stacks/connect` modal
+- `connect('xverse')` with an explicit provider still bypasses the modal
+- The `wallets` prop controls which wallets appear in the modal
+- All 6 wallets are supported in the modal
+- After the user picks a wallet, the kit automatically maps it back and sets state
+
 ### `useConnect()`
 
 ```ts
 const { connect, reset, isPending } = useConnect();
 
+// Open the @stacks/connect modal (when connectModal is enabled, the default)
+await connect();
+
+// Or connect to a specific wallet directly
 await connect('xverse');
 await connect('leather', {
   onSuccess: (address, provider) => {},
@@ -102,16 +125,20 @@ reset();
 
 ### `useWallets()`
 
-Returns all configured wallets with their availability status.
+Returns all configured wallets with their name, icon, download link, and availability status. Metadata is sourced from `@stacks/connect`.
 
 ```ts
 const { wallets } = useWallets();
-// [{ id: 'xverse', available: true }, { id: 'leather', available: false }, ...]
-
-{wallets.map(({ id, available }) => (
-  <button key={id} onClick={() => connect(id)} disabled={!available}>
-    {id}
-  </button>
+// [{ id: 'xverse', name: 'Xverse Wallet', icon: 'data:image/svg+xml;...', webUrl: 'https://xverse.app', available: true }, ...]
+
+{wallets.map(({ id, name, icon, webUrl, available }) => (
+  <div key={id}>
+    <button onClick={() => connect(id)} disabled={!available}>
+      {icon && <img src={icon} alt={name} width={20} height={20} />}
+      {name}
+    </button>
+    {!available && webUrl && <a href={webUrl} target="_blank">Install</a>}
+  </div>
 ))}
 ```
 
@@ -194,14 +221,16 @@ const { supported, installed } = getStacksWallets();
 
 ## Supported Wallets
 
+All 6 wallets work with both headless (`connect('xverse')`) and modal (`connect()`) modes.
+
 | Wallet | ID |
 |---|---|
 | Xverse | `xverse` |
 | Leather | `leather` |
-| OKX | `okx` |
 | Asigna | `asigna` |
 | Fordefi | `fordefi` |
 | WalletConnect | `wallet-connect` |
+| OKX | `okx` |
 
 ## Peer Dependencies
 

package/dist/index.cjs

@@ -10,10 +10,17 @@ var bnsV2Sdk = require('bns-v2-sdk');
 var STACKS_TO_STACKS_CONNECT_PROVIDERS = {
   xverse: "XverseProviders.BitcoinProvider",
   leather: "LeatherProvider",
+  okx: "OkxStacksProvider",
   asigna: "AsignaProvider",
   fordefi: "FordefiProviders.UtxoProvider",
   "wallet-connect": "WalletConnectProvider"
 };
+var STACKS_CONNECT_TO_STACKS_PROVIDERS = Object.fromEntries(
+  Object.entries(STACKS_TO_STACKS_CONNECT_PROVIDERS).map(([kit, connect]) => [
+    connect,
+    kit
+  ])
+);
 
 // src/constants/storage-keys.ts
 var LOCAL_STORAGE_STACKS = "@satoshai/kit";
@@ -22,10 +29,10 @@ var LOCAL_STORAGE_STACKS = "@satoshai/kit";
 var SUPPORTED_STACKS_WALLETS = [
   "xverse",
   "leather",
-  "okx",
   "asigna",
   "fordefi",
-  "wallet-connect"
+  "wallet-connect",
+  "okx"
 ];
 
 // src/utils/get-stacks-wallets.ts
@@ -37,7 +44,7 @@ var getStacksWallets = () => {
   return { supported, installed };
 };
 var checkIfStacksProviderIsInstalled = (wallet) => {
-  if (typeof window === "undefined") return true;
+  if (typeof window === "undefined") return wallet === "wallet-connect";
   switch (wallet) {
     case "xverse":
       return !!window.XverseProviders;
@@ -92,6 +99,38 @@ var getOKXStacksAddress = async () => {
     provider: "okx"
   };
 };
+var OKX_PROVIDER_META = {
+  id: "OkxStacksProvider",
+  name: "OKX Wallet",
+  icon: "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiICAgICB4bWxuczp4b2RtPSJodHRwOi8vd3d3LmNvcmVsLmNvbS9jb3JlbGRyYXcvb2RtLzIwMDMiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHg9IjBweCIgeT0iMHB4IiB2aWV3Qm94PSIwIDAgMjUwMCAyNTAwIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCAyNTAwIDI1MDA7IiB4bWw6c3BhY2U9InByZXNlcnZlIj4KPHN0eWxlIHR5cGU9InRleHQvY3NzIj4KICAgIC5zdDB7ZmlsbC1ydWxlOmV2ZW5vZGQ7Y2xpcC1ydWxlOmV2ZW5vZGQ7fQogICAgLnN0MXtmaWxsOiNGRkZGRkY7fQo8L3N0eWxlPgo8ZyBpZD0iTGF5ZXJfeDAwMjBfMSI+CiAgICA8ZyBpZD0iXzIxODczODEzMjM4NTYiPgogICAgICAgIDxyZWN0IHk9IjAiIGNsYXNzPSJzdDAiIHdpZHRoPSIyNTAwIiBoZWlnaHQ9IjI1MDAiPjwvcmVjdD4KICAgICAgICA8Zz4KICAgICAgICAgICAgPHBhdGggY2xhc3M9InN0MSIgZD0iTTE0NjMsMTAxNWgtNDA0Yy0xNywwLTMxLDE0LTMxLDMxdjQwNGMwLDE3LDE0LDMxLDMxLDMxaDQwNGMxNywwLDMxLTE0LDMxLTMxdi00MDQgICAgIEMxNDk0LDEwMjksMTQ4MCwxMDE1LDE0NjMsMTAxNXoiPjwvcGF0aD4KICAgICAgICAgICAgPHBhdGggY2xhc3M9InN0MSIgZD0iTTk5Niw1NDlINTkyYy0xNywwLTMxLDE0LTMxLDMxdjQwNGMwLDE3LDE0LDMxLDMxLDMxaDQwNGMxNywwLDMxLTE0LDMxLTMxVjU4MEMxMDI3LDU2MywxMDEzLDU0OSw5OTYsNTQ5eiI+PC9wYXRoPgogICAgICAgICAgICA8cGF0aCBjbGFzcz0ic3QxIiBkPSJNMTkzMCw1NDloLTQwNGMtMTcsMC0zMSwxNC0zMSwzMXY0MDRjMCwxNywxNCwzMSwzMSwzMWg0MDRjMTcsMCwzMS0xNCwzMS0zMVY1ODAgICAgIEMxOTYxLDU2MywxOTQ3LDU0OSwxOTMwLDU0OXoiPjwvcGF0aD4KICAgICAgICAgICAgPHBhdGggY2xhc3M9InN0MSIgZD0iTTk5NiwxNDgySDU5MmMtMTcsMC0zMSwxNC0zMSwzMXY0MDRjMCwxNywxNCwzMSwzMSwzMWg0MDRjMTcsMCwzMS0xNCwzMS0zMXYtNDA0ICAgICBDMTAyNywxNDk2LDEwMTMsMTQ4Miw5OTYsMTQ4MnoiPjwvcGF0aD4KICAgICAgICAgICAgPHBhdGggY2xhc3M9InN0MSIgZD0iTTE5MzAsMTQ4MmgtNDA0Yy0xNywwLTMxLDE0LTMxLDMxdjQwNGMwLDE3LDE0LDMxLDMxLDMxaDQwNGMxNywwLDMxLTE0LDMxLTMxdi00MDQgICAgIEMxOTYxLDE0OTYsMTk0NywxNDgyLDE5MzAsMTQ4MnoiPjwvcGF0aD4KICAgICAgICA8L2c+CiAgICA8L2c+CjwvZz4KPC9zdmc+",
+  webUrl: "https://www.okx.com/"
+};
+var registerOkxProvider = () => {
+  if (typeof window === "undefined") return;
+  if (!window.OkxStacksProvider) {
+    window.OkxStacksProvider = {
+      request: async (method) => {
+        if (method === "getAddresses") {
+          const data = await getOKXStacksAddress();
+          return {
+            result: {
+              addresses: [
+                { address: data.address, symbol: "STX" }
+              ]
+            }
+          };
+        }
+        throw new Error(
+          `OKX adapter: unsupported method "${method}". Use connect('okx') for direct OKX SDK access.`
+        );
+      }
+    };
+  }
+};
+var unregisterOkxProvider = () => {
+  if (typeof window === "undefined") return;
+  delete window.OkxStacksProvider;
+};
 var extractStacksAddress = (typedProvider, addresses) => {
   if (!addresses.length) {
     throw new Error(`No addresses provided for ${typedProvider} wallet`);
@@ -223,12 +262,21 @@ var getLocalStorageWallet = () => {
     return null;
   }
 };
+var PROVIDER_META_BY_KIT_ID = Object.fromEntries(
+  [...connect.DEFAULT_PROVIDERS, connect.WALLET_CONNECT_PROVIDER, OKX_PROVIDER_META].map(
+    (p) => [
+      STACKS_CONNECT_TO_STACKS_PROVIDERS[p.id],
+      { name: p.name, icon: p.icon ?? "", webUrl: p.webUrl ?? "" }
+    ]
+  )
+);
 var StacksWalletContext = react.createContext(
   void 0
 );
 var StacksWalletProvider = ({
   children,
   wallets,
+  connectModal = true,
   walletConnect,
   onConnect,
   onAddressChange,
@@ -238,15 +286,23 @@ var StacksWalletProvider = ({
   const [provider, setProvider] = react.useState();
   const [isConnecting, setIsConnecting] = react.useState(false);
   const connectGenRef = react.useRef(0);
+  const wasConnectedRef = react.useRef(false);
   const wcInitRef = react.useRef(null);
+  const walletConnectRef = react.useRef(walletConnect);
+  walletConnectRef.current = walletConnect;
   const walletsKey = wallets?.join(",");
+  if (wallets?.includes("wallet-connect") && !walletConnect?.projectId) {
+    throw new Error(
+      'StacksWalletProvider: "wallet-connect" is listed in wallets but no walletConnect.projectId was provided.'
+    );
+  }
   react.useEffect(() => {
-    if (wallets?.includes("wallet-connect") && !walletConnect?.projectId) {
-      throw new Error(
-        'StacksWalletProvider: "wallet-connect" is listed in wallets but no walletConnect.projectId was provided.'
-      );
+    const okxConfigured = !wallets || wallets.includes("okx");
+    if (connectModal && okxConfigured) {
+      registerOkxProvider();
+      return () => unregisterOkxProvider();
     }
-  }, [walletsKey, walletConnect?.projectId]);
+  }, [connectModal, walletsKey]);
   react.useEffect(() => {
     const loadPersistedWallet = async () => {
       const persisted = getLocalStorageWallet();
@@ -286,6 +342,65 @@ var StacksWalletProvider = ({
   }, [walletConnect?.projectId]);
   const connect$1 = react.useCallback(
     async (providerId, options) => {
+      if (connectModal && !providerId) {
+        const gen2 = ++connectGenRef.current;
+        setIsConnecting(true);
+        try {
+          connect.clearSelectedProviderId();
+          const requestOptions = {
+            forceWalletSelect: true,
+            // OKX at the end so it appears last among installed wallets
+            defaultProviders: [
+              ...connect.DEFAULT_PROVIDERS,
+              OKX_PROVIDER_META
+            ]
+          };
+          if (wallets) {
+            requestOptions.approvedProviderIds = wallets.map(
+              (w) => STACKS_TO_STACKS_CONNECT_PROVIDERS[w]
+            );
+          }
+          const wc2 = walletConnectRef.current;
+          if (wc2?.projectId) {
+            requestOptions.walletConnect = buildWalletConnectConfig(
+              wc2.projectId,
+              wc2.metadata,
+              wc2.chains
+            );
+          }
+          const data = await connect.request(
+            requestOptions,
+            "getAddresses",
+            {}
+          );
+          if (connectGenRef.current !== gen2) return;
+          const selectedId = connect.getSelectedProviderId();
+          const resolvedProvider = selectedId ? STACKS_CONNECT_TO_STACKS_PROVIDERS[selectedId] : void 0;
+          if (!resolvedProvider) {
+            throw new Error(
+              `Unknown provider returned from @stacks/connect modal: ${selectedId ?? "none"}`
+            );
+          }
+          const extractedAddress = extractStacksAddress(
+            resolvedProvider,
+            data.addresses
+          );
+          setAddress(extractedAddress);
+          setProvider(resolvedProvider);
+          options?.onSuccess?.(extractedAddress, resolvedProvider);
+        } catch (error) {
+          if (connectGenRef.current !== gen2) return;
+          console.error("Failed to connect wallet:", error);
+          connect.getSelectedProvider()?.disconnect?.();
+          connect.clearSelectedProviderId();
+          options?.onError?.(error);
+        } finally {
+          if (connectGenRef.current === gen2) {
+            setIsConnecting(false);
+          }
+        }
+        return;
+      }
       const typedProvider = SUPPORTED_STACKS_WALLETS.find(
         (wallet) => wallet === providerId
       );
@@ -305,7 +420,8 @@ var StacksWalletProvider = ({
         options?.onError?.(error);
         return;
       }
-      if (typedProvider === "wallet-connect" && !walletConnect?.projectId) {
+      const wc = walletConnectRef.current;
+      if (typedProvider === "wallet-connect" && !wc?.projectId) {
         const error = new Error(
           "WalletConnect requires a project ID. Please provide walletConnect.projectId to the StacksWalletProvider."
         );
@@ -327,10 +443,10 @@ var StacksWalletProvider = ({
         connect.setSelectedProviderId(
           STACKS_TO_STACKS_CONNECT_PROVIDERS[typedProvider]
         );
-        const wcConfig = typedProvider === "wallet-connect" && walletConnect ? buildWalletConnectConfig(
-          walletConnect.projectId,
-          walletConnect.metadata,
-          walletConnect.chains
+        const wcConfig = typedProvider === "wallet-connect" && wc ? buildWalletConnectConfig(
+          wc.projectId,
+          wc.metadata,
+          wc.chains
         ) : void 0;
         if (wcConfig) {
           if (wcInitRef.current) await wcInitRef.current;
@@ -367,7 +483,7 @@ var StacksWalletProvider = ({
         }
       }
     },
-    [walletConnect]
+    [connectModal, walletsKey]
   );
   const reset = react.useCallback(() => {
     connectGenRef.current++;
@@ -394,24 +510,35 @@ var StacksWalletProvider = ({
     );
   }, [address, provider]);
   react.useEffect(() => {
-    if (!address || !provider || !onConnect) return;
-    onConnect(provider, address);
+    const isConnected = !!address && !!provider;
+    if (isConnected && !wasConnectedRef.current) {
+      onConnect?.(provider, address);
+    }
+    wasConnectedRef.current = isConnected;
   }, [address, provider, onConnect]);
-  useXverse({
-    address,
-    provider,
-    onAddressChange: (newAddress) => {
+  const handleAddressChange = react.useCallback(
+    (newAddress) => {
       setAddress(newAddress);
       onAddressChange?.(newAddress);
     },
+    [onAddressChange]
+  );
+  useXverse({
+    address,
+    provider,
+    onAddressChange: handleAddressChange,
     connect: connect$1
   });
   const { installed } = getStacksWallets();
   const configured = wallets ?? [...SUPPORTED_STACKS_WALLETS];
   const walletInfos = configured.map((w) => ({
     id: w,
+    name: PROVIDER_META_BY_KIT_ID[w]?.name ?? w,
+    icon: PROVIDER_META_BY_KIT_ID[w]?.icon ?? "",
+    webUrl: PROVIDER_META_BY_KIT_ID[w]?.webUrl ?? "",
     available: w === "wallet-connect" ? !!walletConnect?.projectId : installed.includes(w)
   }));
+  const walletInfosKey = walletInfos.map((w) => `${w.id}:${w.available}`).join(",");
   const value = react.useMemo(() => {
     const walletState = isConnecting ? { status: "connecting", address: void 0, provider: void 0 } : address && provider ? { status: "connected", address, provider } : {
       status: "disconnected",
@@ -425,7 +552,7 @@ var StacksWalletProvider = ({
       reset,
       wallets: walletInfos
     };
-  }, [address, provider, isConnecting, connect$1, disconnect, reset, walletInfos]);
+  }, [address, provider, isConnecting, connect$1, disconnect, reset, walletInfosKey]);
   return /* @__PURE__ */ jsxRuntime.jsx(StacksWalletContext.Provider, { value, children });
 };
 var useStacksWalletContext = () => {
@@ -741,20 +868,28 @@ var useBnsName = (address) => {
       setIsLoading(false);
       return;
     }
+    let cancelled = false;
     const fetchBnsName = async () => {
       setIsLoading(true);
       try {
         const network = getNetworkFromAddress(address);
         const result = await bnsV2Sdk.getPrimaryName({ address, network });
+        if (cancelled) return;
         const fullName = result ? `${result.name}.${result.namespace}` : null;
         setBnsName(fullName);
       } catch {
+        if (cancelled) return;
         setBnsName(null);
       } finally {
-        setIsLoading(false);
+        if (!cancelled) {
+          setIsLoading(false);
+        }
       }
     };
     void fetchBnsName();
+    return () => {
+      cancelled = true;
+    };
   }, [address]);
   return { bnsName, isLoading };
 };