@satoshai/kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joao Faustino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,622 @@
+'use strict';
+
+var connect = require('@stacks/connect');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+var transactions = require('@stacks/transactions');
+var bnsV2Sdk = require('bns-v2-sdk');
+
+// src/constants/stacks-provider-mapping.ts
+var STACKS_TO_STACKS_CONNECT_PROVIDERS = {
+  xverse: "XverseProviders.BitcoinProvider",
+  leather: "LeatherProvider",
+  asigna: "AsignaProvider",
+  fordefi: "FordefiProviders.UtxoProvider",
+  "wallet-connect": "WalletConnectProvider"
+};
+
+// src/constants/storage-keys.ts
+var LOCAL_STORAGE_STACKS = "@satoshai/kit";
+
+// src/constants/wallets.ts
+var SUPPORTED_STACKS_WALLETS = [
+  "xverse",
+  "leather",
+  "okx",
+  "asigna",
+  "fordefi",
+  "wallet-connect"
+];
+
+// src/utils/get-stacks-wallets.ts
+var getStacksWallets = () => {
+  const supported = [...SUPPORTED_STACKS_WALLETS];
+  const installed = supported.filter(
+    (wallet) => checkIfStacksProviderIsInstalled(wallet)
+  );
+  return { supported, installed };
+};
+var checkIfStacksProviderIsInstalled = (wallet) => {
+  if (typeof window === "undefined") return true;
+  switch (wallet) {
+    case "xverse":
+      return !!window.XverseProviders;
+    case "leather":
+      return !!window.LeatherProvider || !!window.HiroWalletProvider;
+    case "asigna":
+      return !!window.AsignaProvider;
+    case "okx":
+      return !!window.okxwallet;
+    case "fordefi":
+      return !!window.FordefiProviders?.UtxoProvider;
+    case "wallet-connect":
+      return true;
+  }
+};
+var STACKS_CHAIN_MAPPING = {
+  mainnet: connect.WalletConnect.Chains.Stacks.Mainnet,
+  testnet: connect.WalletConnect.Chains.Stacks.Testnet
+};
+var buildWalletConnectConfig = (projectId, metadata, chains) => {
+  const selectedChains = chains ?? ["mainnet"];
+  const walletConnectChains = selectedChains.map(
+    (chain) => STACKS_CHAIN_MAPPING[chain]
+  );
+  return {
+    projectId,
+    metadata: {
+      name: "Universal Connector",
+      description: "Universal Connector",
+      url: "https://appkit.reown.com",
+      icons: ["https://appkit.reown.com/icon.png"],
+      ...metadata
+    },
+    networks: [
+      {
+        ...connect.WalletConnect.Networks.Stacks,
+        chains: walletConnectChains
+      }
+    ]
+  };
+};
+var getOKXStacksAddress = async () => {
+  if (!window.okxwallet) {
+    throw new Error("\u{1F6A8} OKX Wallet is not installed");
+  }
+  const stacksResponse = await window.okxwallet.stacks.connect();
+  if (!stacksResponse) {
+    throw new Error("\u{1F6A8} Failed to connect with OKX Wallet");
+  }
+  return {
+    address: stacksResponse.address,
+    provider: "okx"
+  };
+};
+var extractStacksAddress = (typedProvider, addresses) => {
+  if (!addresses.length) {
+    throw new Error(`No addresses provided for ${typedProvider} wallet`);
+  }
+  if (typedProvider === "leather" || typedProvider === "asigna") {
+    const stxAddress = addresses.find(
+      (addr) => addr.symbol === "STX"
+    )?.address;
+    if (stxAddress) return stxAddress;
+  }
+  const stacksAddress = addresses.find(
+    (addr) => addr.address?.startsWith("S")
+  )?.address;
+  if (stacksAddress) return stacksAddress;
+  const legacyAddress = addresses[2]?.address;
+  if (legacyAddress?.startsWith("S")) return legacyAddress;
+  throw new Error(
+    `No valid Stacks address found for ${typedProvider} wallet`
+  );
+};
+var getXverseProductInfo = async () => await window.XverseProviders?.StacksProvider?.getProductInfo?.() ?? null;
+var shouldSupportAccountChange = (version) => version !== void 0 && version !== "1.0.0";
+var waitForXverseProvider = async (maxAttempts = 10, initialDelay = 200) => {
+  for (let i = 0; i < maxAttempts; i++) {
+    const provider = connect.getSelectedProvider();
+    if (provider?.request && provider?.addListener) return true;
+    await new Promise(
+      (resolve) => setTimeout(resolve, initialDelay * Math.min(i + 1, 5))
+    );
+  }
+  return false;
+};
+var extractAndValidateStacksAddress = (addresses, currentAddress, onAddressChange, connect) => {
+  if (!addresses || !Array.isArray(addresses)) {
+    void connect();
+    return;
+  }
+  const stacksAccount = addresses.find(
+    (acc) => acc.purpose === "stacks" || acc.addressType === "stacks"
+  );
+  if (!stacksAccount?.address) {
+    void connect();
+    return;
+  }
+  if (stacksAccount.address !== currentAddress) {
+    onAddressChange(stacksAccount.address);
+  }
+};
+
+// src/hooks/use-xverse/use-xverse.ts
+var useXverse = ({
+  address,
+  provider,
+  onAddressChange,
+  connect: connect$1
+}) => {
+  const [isProviderReady, setIsProviderReady] = react.useState(false);
+  react.useEffect(() => {
+    if (provider !== "xverse") return;
+    const checkProvider = async () => {
+      const ready = await waitForXverseProvider();
+      setIsProviderReady(ready);
+      if (!ready) {
+        console.error("Xverse provider failed to initialize");
+      }
+    };
+    void checkProvider();
+  }, [provider]);
+  react.useEffect(() => {
+    if (provider !== "xverse" || !address || !isProviderReady) return;
+    let removeListener;
+    const setupXverse = async () => {
+      try {
+        const productInfo = await getXverseProductInfo();
+        if (!shouldSupportAccountChange(productInfo?.version)) return;
+        const response = await connect.getSelectedProvider()?.request(
+          "wallet_connect",
+          null
+        );
+        extractAndValidateStacksAddress(
+          response?.result?.addresses,
+          address,
+          onAddressChange,
+          () => connect$1("xverse")
+        );
+        removeListener = connect.getSelectedProvider()?.addListener(
+          "accountChange",
+          (event) => {
+            extractAndValidateStacksAddress(
+              event?.addresses,
+              address,
+              onAddressChange,
+              () => connect$1("xverse")
+            );
+          }
+        );
+      } catch (error) {
+        console.error("Failed to setup Xverse:", error);
+      }
+    };
+    void setupXverse();
+    return () => {
+      if (!removeListener) return;
+      try {
+        removeListener();
+      } catch (error) {
+        console.error("Failed to remove Xverse listener:", error);
+      }
+    };
+  }, [address, isProviderReady, onAddressChange, connect$1, provider]);
+};
+
+// src/utils/get-local-storage-wallet.ts
+var getLocalStorageWallet = () => {
+  if (typeof window === "undefined") return null;
+  const stored = localStorage.getItem(LOCAL_STORAGE_STACKS);
+  if (!stored) return null;
+  try {
+    const data = JSON.parse(stored);
+    const isValid = SUPPORTED_STACKS_WALLETS.find(
+      (wallet) => wallet === data.provider
+    );
+    return isValid ? data : null;
+  } catch {
+    return null;
+  }
+};
+var StacksWalletContext = react.createContext(
+  void 0
+);
+var StacksWalletProvider = ({
+  children,
+  walletConnect,
+  onConnect,
+  onAddressChange,
+  onDisconnect
+}) => {
+  const [address, setAddress] = react.useState();
+  const [provider, setProvider] = react.useState();
+  const [isConnecting, setIsConnecting] = react.useState(false);
+  react.useEffect(() => {
+    const loadPersistedWallet = async () => {
+      const persisted = getLocalStorageWallet();
+      if (!persisted) return;
+      setIsConnecting(true);
+      try {
+        if (persisted.provider === "okx") {
+          const data = await getOKXStacksAddress();
+          setAddress(data.address);
+          setProvider(data.provider);
+          return;
+        }
+        setAddress(persisted.address);
+        setProvider(persisted.provider);
+        connect.setSelectedProviderId(
+          STACKS_TO_STACKS_CONNECT_PROVIDERS[persisted.provider]
+        );
+      } catch (error) {
+        console.error("Failed to restore wallet connection:", error);
+      } finally {
+        setIsConnecting(false);
+      }
+    };
+    void loadPersistedWallet();
+  }, []);
+  const connect$1 = react.useCallback(
+    async (providerId, options) => {
+      const typedProvider = SUPPORTED_STACKS_WALLETS.find(
+        (wallet) => wallet === providerId
+      );
+      if (!typedProvider) {
+        const error = new Error(
+          "The wallet provider selected is not supported!"
+        );
+        console.error("\u{1F6A8}", error.message);
+        options?.onError?.(error);
+        return;
+      }
+      if (!checkIfStacksProviderIsInstalled(typedProvider)) {
+        const error = new Error(
+          `${typedProvider} wallet is not installed. Please install the wallet extension to continue.`
+        );
+        console.error("\u{1F6A8}", error.message);
+        options?.onError?.(error);
+        return;
+      }
+      if (typedProvider === "wallet-connect" && !walletConnect?.projectId) {
+        const error = new Error(
+          "WalletConnect requires a project ID. Please provide walletConnect.projectId to the StacksWalletProvider."
+        );
+        console.error("\u{1F6A8}", error.message);
+        options?.onError?.(error);
+        return;
+      }
+      setIsConnecting(true);
+      try {
+        if (typedProvider === "okx") {
+          const data2 = await getOKXStacksAddress();
+          setAddress(data2.address);
+          setProvider(data2.provider);
+          options?.onSuccess?.(data2.address, data2.provider);
+          return;
+        }
+        connect.setSelectedProviderId(
+          STACKS_TO_STACKS_CONNECT_PROVIDERS[typedProvider]
+        );
+        const data = walletConnect ? await connect.request(
+          {
+            walletConnect: buildWalletConnectConfig(
+              walletConnect.projectId,
+              walletConnect.metadata,
+              walletConnect.chains
+            )
+          },
+          "getAddresses",
+          {}
+        ) : await connect.request("getAddresses");
+        const extractedAddress = extractStacksAddress(
+          typedProvider,
+          data.addresses
+        );
+        setAddress(extractedAddress);
+        setProvider(typedProvider);
+        options?.onSuccess?.(extractedAddress, typedProvider);
+      } catch (error) {
+        console.error("Failed to connect wallet:", error);
+        connect.getSelectedProvider()?.disconnect?.();
+        connect.clearSelectedProviderId();
+        options?.onError?.(error);
+      } finally {
+        setIsConnecting(false);
+      }
+    },
+    [walletConnect]
+  );
+  const disconnect = react.useCallback(
+    (callback) => {
+      localStorage.removeItem(LOCAL_STORAGE_STACKS);
+      setAddress(void 0);
+      setProvider(void 0);
+      connect.getSelectedProvider()?.disconnect?.();
+      connect.clearSelectedProviderId();
+      callback?.();
+      onDisconnect?.();
+    },
+    [onDisconnect]
+  );
+  react.useEffect(() => {
+    if (!address || !provider) return;
+    localStorage.setItem(
+      LOCAL_STORAGE_STACKS,
+      JSON.stringify({ address, provider })
+    );
+  }, [address, provider]);
+  react.useEffect(() => {
+    if (!address || !provider || !onConnect) return;
+    onConnect(provider, address);
+  }, [address, provider, onConnect]);
+  useXverse({
+    address,
+    provider,
+    onAddressChange: (newAddress) => {
+      setAddress(newAddress);
+      onAddressChange?.(newAddress);
+    },
+    connect: connect$1
+  });
+  const value = react.useMemo(() => {
+    const walletState = isConnecting ? { status: "connecting", address: void 0, provider: void 0 } : address && provider ? { status: "connected", address, provider } : {
+      status: "disconnected",
+      address: void 0,
+      provider: void 0
+    };
+    return {
+      ...walletState,
+      connect: connect$1,
+      disconnect
+    };
+  }, [address, provider, isConnecting, connect$1, disconnect]);
+  return /* @__PURE__ */ jsxRuntime.jsx(StacksWalletContext.Provider, { value, children });
+};
+var useStacksWalletContext = () => {
+  const context = react.useContext(StacksWalletContext);
+  if (context === void 0) {
+    throw new Error(
+      "\u{1F6A8} Stacks wallet hooks must be used within StacksWalletProvider"
+    );
+  }
+  return context;
+};
+var useAddress = () => {
+  const { address, status, provider } = useStacksWalletContext();
+  return react.useMemo(() => {
+    if (status === "connected" && address && provider) {
+      return {
+        address,
+        isConnected: true,
+        isConnecting: false,
+        isDisconnected: false,
+        provider
+      };
+    }
+    return {
+      address: void 0,
+      isConnected: false,
+      isConnecting: status === "connecting",
+      isDisconnected: status === "disconnected",
+      provider: void 0
+    };
+  }, [address, status, provider]);
+};
+var useConnect = () => {
+  const { connect, status } = useStacksWalletContext();
+  const value = react.useMemo(
+    () => ({
+      connect,
+      connectors: SUPPORTED_STACKS_WALLETS,
+      isPending: status === "connecting"
+    }),
+    [connect, status]
+  );
+  return value;
+};
+var useDisconnect = () => {
+  const { disconnect } = useStacksWalletContext();
+  return react.useMemo(
+    () => ({
+      disconnect
+    }),
+    [disconnect]
+  );
+};
+var useSignMessage = () => {
+  const { isConnected, provider } = useAddress();
+  const [data, setData] = react.useState(void 0);
+  const [error, setError] = react.useState(null);
+  const [isPending, setIsPending] = react.useState(false);
+  const signMessageAsync = react.useCallback(
+    async (variables) => {
+      if (!isConnected) {
+        throw new Error("Wallet is not connected");
+      }
+      setIsPending(true);
+      setError(null);
+      setData(void 0);
+      try {
+        let result;
+        if (provider === "okx") {
+          if (!window.okxwallet) {
+            throw new Error("OKX wallet not found");
+          }
+          result = await window.okxwallet.stacks.signMessage({
+            message: variables.message
+          });
+        } else {
+          result = await connect.request("stx_signMessage", {
+            message: variables.message,
+            ...variables.publicKey && {
+              publicKey: variables.publicKey
+            }
+          });
+        }
+        setData(result);
+        setIsPending(false);
+        return result;
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        setError(error2);
+        setIsPending(false);
+        throw error2;
+      }
+    },
+    [isConnected, provider]
+  );
+  const signMessage = react.useCallback(
+    (variables, options) => {
+      signMessageAsync(variables).then((data2) => {
+        options?.onSuccess?.(data2);
+        options?.onSettled?.(data2, null);
+      }).catch((error2) => {
+        options?.onError?.(error2);
+        options?.onSettled?.(void 0, error2);
+      });
+    },
+    [signMessageAsync]
+  );
+  return {
+    signMessage,
+    signMessageAsync,
+    data,
+    error,
+    isPending
+  };
+};
+
+// src/utils/get-network-from-address.ts
+var getNetworkFromAddress = (address) => {
+  if (address.startsWith("SP") || address.startsWith("SM")) {
+    return "mainnet";
+  }
+  if (address.startsWith("ST") || address.startsWith("SN")) {
+    return "testnet";
+  }
+  throw new Error(`Invalid Stacks address: ${address}`);
+};
+var preparePostConditionsForOKX = (postConditions) => postConditions.map((pc) => transactions.postConditionToHex(pc));
+var prepareArgsForOKX = (args) => args.map((arg) => transactions.cvToHex(arg));
+
+// src/hooks/use-write-contract/use-write-contract.ts
+var useWriteContract = () => {
+  const { isConnected, address, provider } = useAddress();
+  const [data, setData] = react.useState(void 0);
+  const [error, setError] = react.useState(null);
+  const [isPending, setIsPending] = react.useState(false);
+  const writeContractAsync = react.useCallback(
+    async (variables) => {
+      if (!isConnected || !address) {
+        throw new Error("Wallet is not connected");
+      }
+      setIsPending(true);
+      setError(null);
+      setData(void 0);
+      try {
+        if (provider === "okx") {
+          if (!window.okxwallet) {
+            throw new Error("OKX wallet not found");
+          }
+          const response2 = await window.okxwallet.stacks.signTransaction({
+            contractAddress: variables.address,
+            contractName: variables.contract,
+            functionName: variables.functionName,
+            functionArgs: prepareArgsForOKX(variables.args),
+            postConditions: preparePostConditionsForOKX(
+              variables.pc.postConditions
+            ),
+            postConditionMode: variables.pc.mode,
+            stxAddress: address,
+            txType: "contract_call",
+            anchorMode: 3
+          });
+          setData(response2.txHash);
+          setIsPending(false);
+          return response2.txHash;
+        }
+        const response = await connect.request("stx_callContract", {
+          address,
+          contract: `${variables.address}.${variables.contract}`,
+          functionName: variables.functionName,
+          functionArgs: variables.args,
+          postConditions: variables.pc.postConditions,
+          postConditionMode: variables.pc.mode === transactions.PostConditionMode.Allow ? "allow" : "deny",
+          network: getNetworkFromAddress(address)
+        });
+        if (!response.txid) {
+          throw new Error("No transaction ID returned");
+        }
+        setData(response.txid);
+        setIsPending(false);
+        return response.txid;
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        setError(error2);
+        setIsPending(false);
+        throw error2;
+      }
+    },
+    [isConnected, address, provider]
+  );
+  const writeContract = react.useCallback(
+    (variables, options) => {
+      writeContractAsync(variables).then((data2) => {
+        options?.onSuccess?.(data2);
+        options?.onSettled?.(data2, null);
+      }).catch((error2) => {
+        options?.onError?.(error2);
+        options?.onSettled?.(void 0, error2);
+      });
+    },
+    [writeContractAsync]
+  );
+  return {
+    writeContract,
+    writeContractAsync,
+    data,
+    error,
+    isPending
+  };
+};
+var useBnsName = (address) => {
+  const [bnsName, setBnsName] = react.useState(null);
+  const [isLoading, setIsLoading] = react.useState(false);
+  react.useEffect(() => {
+    if (!address) {
+      setBnsName(null);
+      setIsLoading(false);
+      return;
+    }
+    const fetchBnsName = async () => {
+      setIsLoading(true);
+      try {
+        const network = getNetworkFromAddress(address);
+        const result = await bnsV2Sdk.getPrimaryName({ address, network });
+        const fullName = result ? `${result.name}.${result.namespace}` : null;
+        setBnsName(fullName);
+      } catch {
+        setBnsName(null);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+    void fetchBnsName();
+  }, [address]);
+  return { bnsName, isLoading };
+};
+
+exports.SUPPORTED_STACKS_WALLETS = SUPPORTED_STACKS_WALLETS;
+exports.StacksWalletProvider = StacksWalletProvider;
+exports.getLocalStorageWallet = getLocalStorageWallet;
+exports.getNetworkFromAddress = getNetworkFromAddress;
+exports.getStacksWallets = getStacksWallets;
+exports.useAddress = useAddress;
+exports.useBnsName = useBnsName;
+exports.useConnect = useConnect;
+exports.useDisconnect = useDisconnect;
+exports.useSignMessage = useSignMessage;
+exports.useWriteContract = useWriteContract;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map