@satoshai/kit 0.6.0 → 0.7.0

package/README.md

@@ -317,6 +317,29 @@ All 6 wallets work with both headless (`connect('xverse')`) and modal (`connect(
 | WalletConnect | `wallet-connect` |
 | OKX | `okx` |
 
+### Wallet Support Matrix
+
+| Hook | Xverse | Leather | Asigna | Fordefi | WalletConnect | OKX |
+|------|--------|---------|--------|---------|---------------|-----|
+| `useConnect` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `useSignMessage` | ✓ | ✓ | ? | ? | ~ | ✓ |
+| `useSignStructuredMessage` | ✓ | ✓ | ? | ? | ~ | ✗ |
+| `useSignTransaction` | ✓ | ✓ | ? | ? | ~ | ✗ |
+| `useWriteContract` | ✓ | ✓ | ✓ | ✓ | ~ | ✓ |
+| `useTransferSTX` | ✓ | ✓ | ✓ | ✓ | ~ | ✓ |
+
+✓ Confirmed supported | ✗ Unsupported (throws error) | ? Unverified | ~ Depends on the connected wallet
+
+**Notes:**
+
+- **OKX** uses a proprietary API (`window.okxwallet.stacks`) instead of the standard `@stacks/connect` RPC. `useSignStructuredMessage` and `useSignTransaction` are explicitly unsupported and will throw.
+- **Asigna** is a multisig wallet. Transaction-based hooks (`useWriteContract`, `useTransferSTX`) work, but message signing hooks may be limited since there is no multisig message signature standard on Stacks.
+- **Fordefi** supports transactions and contract calls on Stacks, but their [supported blockchains](https://docs.fordefi.com/docs/supported-blockchains) page does not list Stacks under message signing capabilities.
+- **WalletConnect** is a relay protocol — all methods are forwarded, but actual support depends on the wallet on the other end.
+- **Xverse** and **Leather** implement the full [SIP-030](https://github.com/janniks/sips/blob/main/sips/sip-030/sip-030-wallet-interface.md) interface.
+
+This matrix was compiled from wallet documentation as of March 2026. Sources: [Xverse Sats Connect docs](https://docs.xverse.app/sats-connect/stacks-methods), [Leather developer docs](https://leather.gitbook.io/developers), [Asigna docs](https://asigna.gitbook.io/asigna), [Fordefi docs](https://docs.fordefi.com/docs/supported-blockchains), [@stacks/connect WalletConnect source](https://github.com/stx-labs/connect/tree/main/packages/connect/src/walletconnect).
+
 ## Peer Dependencies
 
 - `react` ^18 or ^19

package/dist/index.cjs

@@ -6,6 +6,69 @@ var jsxRuntime = require('react/jsx-runtime');
 var transactions = require('@stacks/transactions');
 var bnsV2Sdk = require('bns-v2-sdk');
 
+// src/errors.ts
+var BaseError = class extends Error {
+  name = "StacksKitError";
+  shortMessage;
+  constructor(shortMessage, options) {
+    const message = [
+      shortMessage,
+      options?.details && `Details: ${options.details}`
+    ].filter(Boolean).join("\n\n");
+    super(message, options?.cause ? { cause: options.cause } : void 0);
+    this.shortMessage = shortMessage;
+  }
+  walk(fn) {
+    return walk(this, fn);
+  }
+};
+function walk(err, fn) {
+  if (fn?.(err)) return err;
+  if (err && typeof err === "object" && "cause" in err) {
+    return walk(err.cause, fn);
+  }
+  return err;
+}
+var WalletNotConnectedError = class extends BaseError {
+  name = "WalletNotConnectedError";
+  constructor() {
+    super("Wallet is not connected");
+  }
+};
+var WalletNotFoundError = class extends BaseError {
+  name = "WalletNotFoundError";
+  wallet;
+  constructor({ wallet }) {
+    super(`${wallet} wallet not found`, {
+      details: "The wallet extension may not be installed."
+    });
+    this.wallet = wallet;
+  }
+};
+var UnsupportedMethodError = class extends BaseError {
+  name = "UnsupportedMethodError";
+  method;
+  wallet;
+  constructor({ method, wallet }) {
+    super(`${method} is not supported by ${wallet} wallet`);
+    this.method = method;
+    this.wallet = wallet;
+  }
+};
+var WalletRequestError = class extends BaseError {
+  name = "WalletRequestError";
+  method;
+  wallet;
+  constructor({ method, wallet, cause }) {
+    super(`${wallet} wallet request failed`, {
+      cause,
+      details: cause.message
+    });
+    this.method = method;
+    this.wallet = wallet;
+  }
+};
+
 // src/constants/stacks-provider-mapping.ts
 var STACKS_TO_STACKS_CONNECT_PROVIDERS = {
   xverse: "XverseProviders.BitcoinProvider",
@@ -685,7 +748,7 @@ var useSignMessage = () => {
   const signMessageAsync = react.useCallback(
     async (variables) => {
       if (!isConnected) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       setStatus("pending");
       setError(null);
@@ -694,7 +757,7 @@ var useSignMessage = () => {
         let result;
         if (provider === "okx") {
           if (!window.okxwallet) {
-            throw new Error("OKX wallet not found");
+            throw new WalletNotFoundError({ wallet: "OKX" });
           }
           result = await window.okxwallet.stacks.signMessage({
             message: variables.message
@@ -711,7 +774,11 @@ var useSignMessage = () => {
         setStatus("success");
         return result;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_signMessage",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -762,12 +829,13 @@ var useSignStructuredMessage = () => {
   const signStructuredMessageAsync = react.useCallback(
     async (variables) => {
       if (!isConnected) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       if (provider === "okx") {
-        throw new Error(
-          "Structured message signing is not supported by OKX wallet"
-        );
+        throw new UnsupportedMethodError({
+          method: "stx_signStructuredMessage",
+          wallet: "OKX"
+        });
       }
       setStatus("pending");
       setError(null);
@@ -781,7 +849,11 @@ var useSignStructuredMessage = () => {
         setStatus("success");
         return result;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_signStructuredMessage",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -837,12 +909,13 @@ var useSignTransaction = () => {
   const signTransactionAsync = react.useCallback(
     async (variables) => {
       if (!isConnected) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       if (provider === "okx") {
-        throw new Error(
-          "Transaction signing is not supported by OKX wallet"
-        );
+        throw new UnsupportedMethodError({
+          method: "stx_signTransaction",
+          wallet: "OKX"
+        });
       }
       setStatus("pending");
       setError(null);
@@ -858,7 +931,11 @@ var useSignTransaction = () => {
         setStatus("success");
         return result;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_signTransaction",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -920,7 +997,7 @@ var useTransferSTX = () => {
   const transferSTXAsync = react.useCallback(
     async (variables) => {
       if (!isConnected || !address) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       setStatus("pending");
       setError(null);
@@ -928,7 +1005,7 @@ var useTransferSTX = () => {
       try {
         if (provider === "okx") {
           if (!window.okxwallet) {
-            throw new Error("OKX wallet not found");
+            throw new WalletNotFoundError({ wallet: "OKX" });
           }
           const response2 = await window.okxwallet.stacks.signTransaction({
             txType: "token_transfer",
@@ -963,7 +1040,11 @@ var useTransferSTX = () => {
         setStatus("success");
         return response.txid;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_transferStx",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -1151,7 +1232,7 @@ var useWriteContract = () => {
   const writeContractAsync = react.useCallback(
     async (variables) => {
       if (!isConnected || !address) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       setStatus("pending");
       setError(null);
@@ -1160,7 +1241,7 @@ var useWriteContract = () => {
       try {
         if (provider === "okx") {
           if (!window.okxwallet) {
-            throw new Error("OKX wallet not found");
+            throw new WalletNotFoundError({ wallet: "OKX" });
           }
           const response2 = await window.okxwallet.stacks.signTransaction({
             contractAddress: variables.address,
@@ -1195,7 +1276,11 @@ var useWriteContract = () => {
         setStatus("success");
         return response.txid;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_callContract",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -1280,8 +1365,13 @@ function createContractConfig(config) {
   return config;
 }
 
+exports.BaseError = BaseError;
 exports.SUPPORTED_STACKS_WALLETS = SUPPORTED_STACKS_WALLETS;
 exports.StacksWalletProvider = StacksWalletProvider;
+exports.UnsupportedMethodError = UnsupportedMethodError;
+exports.WalletNotConnectedError = WalletNotConnectedError;
+exports.WalletNotFoundError = WalletNotFoundError;
+exports.WalletRequestError = WalletRequestError;
 exports.createContractConfig = createContractConfig;
 exports.getLocalStorageWallet = getLocalStorageWallet;
 exports.getNetworkFromAddress = getNetworkFromAddress;