@satoshai/kit 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Joao Faustino
+Copyright (c) 2026 Satoshai
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,214 @@
+# @satoshai/kit
+
+Typesafe Stacks wallet & contract interaction library for React. Wagmi-inspired hook API for connecting wallets, signing messages, and calling contracts on the Stacks blockchain.
+
+## Features
+
+- **`StacksWalletProvider`** — React context provider for wallet state
+- **`useConnect` / `useDisconnect`** — Connect and disconnect wallets
+- **`useWallets`** — Configured wallets with availability status
+- **`useAddress`** — Access connected wallet address and status
+- **`useSignMessage`** — Sign arbitrary messages
+- **`useWriteContract`** — Call smart contracts with post-conditions
+- **`useBnsName`** — Resolve BNS v2 names
+- **6 wallets supported** — Xverse, Leather, OKX, Asigna, Fordefi, WalletConnect
+- **Next.js App Router compatible** — `"use client"` directives included
+
+## Install
+
+```bash
+pnpm add @satoshai/kit @stacks/transactions react react-dom
+```
+
+## Quick Start
+
+```tsx
+import { StacksWalletProvider, useConnect, useWallets, useAddress, useDisconnect } from '@satoshai/kit';
+
+function App() {
+  return (
+    <StacksWalletProvider>
+      <Wallet />
+    </StacksWalletProvider>
+  );
+}
+
+function Wallet() {
+  const { connect, reset, isPending } = useConnect();
+  const { wallets } = useWallets();
+  const { address, isConnected } = useAddress();
+  const { disconnect } = useDisconnect();
+
+  if (isConnected) {
+    return (
+      <div>
+        <p>Connected: {address}</p>
+        <button onClick={() => disconnect()}>Disconnect</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {isPending && <button onClick={reset}>Cancel</button>}
+      {wallets.map(({ id, available }) => (
+        <button key={id} onClick={() => connect(id)} disabled={!available || isPending}>
+          {id}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+## API
+
+### `<StacksWalletProvider>`
+
+Wrap your app to provide wallet context to all hooks.
+
+```tsx
+<StacksWalletProvider
+  wallets={['xverse', 'leather', 'wallet-connect']}  // optional — defaults to all supported
+  walletConnect={{ projectId: '...' }}                 // optional — enables WalletConnect
+  onConnect={(provider, address) => {}}                // optional
+  onAddressChange={(newAddress) => {}}                 // optional — Xverse account switching
+  onDisconnect={() => {}}                              // optional
+>
+  {children}
+</StacksWalletProvider>
+```
+
+> If `wallets` includes `'wallet-connect'`, you must provide `walletConnect.projectId` or the provider will throw at mount.
+
+> **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.
+
+### `useConnect()`
+
+```ts
+const { connect, reset, isPending } = useConnect();
+
+await connect('xverse');
+await connect('leather', {
+  onSuccess: (address, provider) => {},
+  onError: (error) => {},
+});
+
+// Reset stuck connecting state (e.g. when a wallet modal is dismissed)
+reset();
+```
+
+> **Note:** Some wallets (e.g. OKX) never reject the connection promise when the user closes the popup. Use `reset()` to clear the pending state in those cases.
+
+### `useWallets()`
+
+Returns all configured wallets with their availability status.
+
+```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>
+))}
+```
+
+A wallet is `available` when its browser extension is installed. For `wallet-connect`, it's `available` when a `walletConnect.projectId` is provided to the provider.
+
+### `useDisconnect()`
+
+```ts
+const { disconnect } = useDisconnect();
+
+disconnect();
+disconnect(() => { /* callback after disconnect */ });
+```
+
+### `useAddress()`
+
+```ts
+const { address, isConnected, isConnecting, isDisconnected, provider } = useAddress();
+
+if (isConnected) {
+  console.log(address);  // 'SP...' or 'ST...'
+  console.log(provider); // 'xverse' | 'leather' | ...
+}
+```
+
+### `useSignMessage()`
+
+```ts
+const { signMessage, signMessageAsync, data, error, isPending } = useSignMessage();
+
+// Callback style
+signMessage({ message: 'Hello Stacks' }, {
+  onSuccess: ({ publicKey, signature }) => {},
+  onError: (error) => {},
+});
+
+// Async style
+const { publicKey, signature } = await signMessageAsync({ message: 'Hello Stacks' });
+```
+
+### `useWriteContract()`
+
+```ts
+import { Pc, PostConditionMode } from '@stacks/transactions';
+
+const { writeContract, writeContractAsync, data, error, isPending } = useWriteContract();
+
+writeContract({
+  address: 'SP...',
+  contract: 'my-contract',
+  functionName: 'my-function',
+  args: [uintCV(100)],
+  pc: {
+    postConditions: [Pc.principal('SP...').willSendLte(100n).ustx()],
+    mode: PostConditionMode.Deny,
+  },
+}, {
+  onSuccess: (txHash) => {},
+  onError: (error) => {},
+});
+```
+
+### `useBnsName()`
+
+```ts
+const { bnsName, isLoading } = useBnsName(address);
+// bnsName = 'satoshi.btc' | null
+```
+
+### Utilities
+
+```ts
+import { getNetworkFromAddress, getStacksWallets, getLocalStorageWallet } from '@satoshai/kit';
+
+getNetworkFromAddress('SP...');  // 'mainnet'
+getNetworkFromAddress('ST...');  // 'testnet'
+
+const { supported, installed } = getStacksWallets();
+```
+
+## Supported Wallets
+
+| Wallet | ID |
+|---|---|
+| Xverse | `xverse` |
+| Leather | `leather` |
+| OKX | `okx` |
+| Asigna | `asigna` |
+| Fordefi | `fordefi` |
+| WalletConnect | `wallet-connect` |
+
+## Peer Dependencies
+
+- `react` ^18 or ^19
+- `react-dom` ^18 or ^19
+- `@stacks/transactions` >=7.0.0
+
+## License
+
+MIT

package/dist/index.cjs

@@ -162,15 +162,18 @@ var useXverse = ({
   }, [provider]);
   react.useEffect(() => {
     if (provider !== "xverse" || !address || !isProviderReady) return;
+    let cancelled = false;
     let removeListener;
     const setupXverse = async () => {
       try {
         const productInfo = await getXverseProductInfo();
+        if (cancelled) return;
         if (!shouldSupportAccountChange(productInfo?.version)) return;
         const response = await connect.getSelectedProvider()?.request(
           "wallet_connect",
           null
         );
+        if (cancelled) return;
         extractAndValidateStacksAddress(
           response?.result?.addresses,
           address,
@@ -194,6 +197,7 @@ var useXverse = ({
     };
     void setupXverse();
     return () => {
+      cancelled = true;
       if (!removeListener) return;
       try {
         removeListener();
@@ -224,6 +228,7 @@ var StacksWalletContext = react.createContext(
 );
 var StacksWalletProvider = ({
   children,
+  wallets,
   walletConnect,
   onConnect,
   onAddressChange,
@@ -232,6 +237,16 @@ var StacksWalletProvider = ({
   const [address, setAddress] = react.useState();
   const [provider, setProvider] = react.useState();
   const [isConnecting, setIsConnecting] = react.useState(false);
+  const connectGenRef = react.useRef(0);
+  const wcInitRef = react.useRef(null);
+  const walletsKey = wallets?.join(",");
+  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.'
+      );
+    }
+  }, [walletsKey, walletConnect?.projectId]);
   react.useEffect(() => {
     const loadPersistedWallet = async () => {
       const persisted = getLocalStorageWallet();
@@ -244,6 +259,18 @@ var StacksWalletProvider = ({
           setProvider(data.provider);
           return;
         }
+        if (persisted.provider === "wallet-connect" && walletConnect?.projectId) {
+          const initPromise = connect.WalletConnect.initializeProvider(
+            buildWalletConnectConfig(
+              walletConnect.projectId,
+              walletConnect.metadata,
+              walletConnect.chains
+            )
+          );
+          wcInitRef.current = initPromise;
+          await initPromise;
+          wcInitRef.current = null;
+        }
         setAddress(persisted.address);
         setProvider(persisted.provider);
         connect.setSelectedProviderId(
@@ -256,7 +283,7 @@ var StacksWalletProvider = ({
       }
     };
     void loadPersistedWallet();
-  }, []);
+  }, [walletConnect?.projectId]);
   const connect$1 = react.useCallback(
     async (providerId, options) => {
       const typedProvider = SUPPORTED_STACKS_WALLETS.find(
@@ -286,10 +313,12 @@ var StacksWalletProvider = ({
         options?.onError?.(error);
         return;
       }
+      const gen = ++connectGenRef.current;
       setIsConnecting(true);
       try {
         if (typedProvider === "okx") {
           const data2 = await getOKXStacksAddress();
+          if (connectGenRef.current !== gen) return;
           setAddress(data2.address);
           setProvider(data2.provider);
           options?.onSuccess?.(data2.address, data2.provider);
@@ -298,17 +327,25 @@ var StacksWalletProvider = ({
         connect.setSelectedProviderId(
           STACKS_TO_STACKS_CONNECT_PROVIDERS[typedProvider]
         );
-        const data = walletConnect ? await connect.request(
-          {
-            walletConnect: buildWalletConnectConfig(
-              walletConnect.projectId,
-              walletConnect.metadata,
-              walletConnect.chains
-            )
-          },
+        const wcConfig = typedProvider === "wallet-connect" && walletConnect ? buildWalletConnectConfig(
+          walletConnect.projectId,
+          walletConnect.metadata,
+          walletConnect.chains
+        ) : void 0;
+        if (wcConfig) {
+          if (wcInitRef.current) await wcInitRef.current;
+          const initPromise = connect.WalletConnect.initializeProvider(wcConfig);
+          wcInitRef.current = initPromise;
+          await initPromise;
+          wcInitRef.current = null;
+        }
+        if (connectGenRef.current !== gen) return;
+        const data = wcConfig ? await connect.request(
+          { walletConnect: wcConfig },
           "getAddresses",
           {}
         ) : await connect.request("getAddresses");
+        if (connectGenRef.current !== gen) return;
         const extractedAddress = extractStacksAddress(
           typedProvider,
           data.addresses
@@ -317,16 +354,26 @@ var StacksWalletProvider = ({
         setProvider(typedProvider);
         options?.onSuccess?.(extractedAddress, typedProvider);
       } catch (error) {
+        if (connectGenRef.current !== gen) return;
         console.error("Failed to connect wallet:", error);
-        connect.getSelectedProvider()?.disconnect?.();
-        connect.clearSelectedProviderId();
+        if (typedProvider !== "okx") {
+          connect.getSelectedProvider()?.disconnect?.();
+          connect.clearSelectedProviderId();
+        }
         options?.onError?.(error);
       } finally {
-        setIsConnecting(false);
+        if (connectGenRef.current === gen) {
+          setIsConnecting(false);
+        }
       }
     },
     [walletConnect]
   );
+  const reset = react.useCallback(() => {
+    connectGenRef.current++;
+    setIsConnecting(false);
+    connect.clearSelectedProviderId();
+  }, []);
   const disconnect = react.useCallback(
     (callback) => {
       localStorage.removeItem(LOCAL_STORAGE_STACKS);
@@ -359,6 +406,14 @@ var StacksWalletProvider = ({
     },
     connect: connect$1
   });
+  const walletInfos = react.useMemo(() => {
+    const { installed } = getStacksWallets();
+    const configured = wallets ?? [...SUPPORTED_STACKS_WALLETS];
+    return configured.map((w) => ({
+      id: w,
+      available: w === "wallet-connect" ? !!walletConnect?.projectId : installed.includes(w)
+    }));
+  }, [walletsKey, walletConnect?.projectId]);
   const value = react.useMemo(() => {
     const walletState = isConnecting ? { status: "connecting", address: void 0, provider: void 0 } : address && provider ? { status: "connected", address, provider } : {
       status: "disconnected",
@@ -368,9 +423,11 @@ var StacksWalletProvider = ({
     return {
       ...walletState,
       connect: connect$1,
-      disconnect
+      disconnect,
+      reset,
+      wallets: walletInfos
     };
-  }, [address, provider, isConnecting, connect$1, disconnect]);
+  }, [address, provider, isConnecting, connect$1, disconnect, reset, walletInfos]);
   return /* @__PURE__ */ jsxRuntime.jsx(StacksWalletContext.Provider, { value, children });
 };
 var useStacksWalletContext = () => {
@@ -404,14 +461,14 @@ var useAddress = () => {
   }, [address, status, provider]);
 };
 var useConnect = () => {
-  const { connect, status } = useStacksWalletContext();
+  const { connect, reset, status } = useStacksWalletContext();
   const value = react.useMemo(
     () => ({
       connect,
-      connectors: SUPPORTED_STACKS_WALLETS,
+      reset,
       isPending: status === "connecting"
     }),
-    [connect, status]
+    [connect, reset, status]
   );
   return value;
 };
@@ -606,6 +663,10 @@ var useBnsName = (address) => {
   }, [address]);
   return { bnsName, isLoading };
 };
+var useWallets = () => {
+  const { wallets } = useStacksWalletContext();
+  return react.useMemo(() => ({ wallets }), [wallets]);
+};
 
 exports.SUPPORTED_STACKS_WALLETS = SUPPORTED_STACKS_WALLETS;
 exports.StacksWalletProvider = StacksWalletProvider;
@@ -617,6 +678,7 @@ exports.useBnsName = useBnsName;
 exports.useConnect = useConnect;
 exports.useDisconnect = useDisconnect;
 exports.useSignMessage = useSignMessage;
+exports.useWallets = useWallets;
 exports.useWriteContract = useWriteContract;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map