@satoshai/kit 0.5.0 → 0.7.0

package/README.md

@@ -1,5 +1,9 @@
 # @satoshai/kit
 
+[![npm version](https://img.shields.io/npm/v/@satoshai/kit)](https://www.npmjs.com/package/@satoshai/kit)
+[![CI](https://github.com/satoshai-dev/kit/actions/workflows/ci.yml/badge.svg)](https://github.com/satoshai-dev/kit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 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
@@ -9,6 +13,8 @@ Typesafe Stacks wallet & contract interaction library for React. Wagmi-inspired
 - **`useWallets`** — Configured wallets with availability status
 - **`useAddress`** — Access connected wallet address and status
 - **`useSignMessage`** — Sign arbitrary messages
+- **`useSignStructuredMessage`** — Sign SIP-018 structured data
+- **`useSignTransaction`** — Sign serialized transactions (sponsored tx flows)
 - **`useWriteContract`** — Call smart contracts with post-conditions
 - **`useTransferSTX`** — Native STX transfers
 - **`useBnsName`** — Resolve BNS v2 names
@@ -180,6 +186,40 @@ signMessage({ message: 'Hello Stacks' }, {
 const { publicKey, signature } = await signMessageAsync({ message: 'Hello Stacks' });
 ```
 
+### `useSignStructuredMessage()`
+
+Sign SIP-018 structured data for typed, verifiable off-chain messages.
+
+> **Note:** OKX wallet does not support structured message signing and will throw an error.
+
+```ts
+import { tupleCV, stringAsciiCV, uintCV } from '@stacks/transactions';
+
+const { signStructuredMessage, signStructuredMessageAsync, data, error, isPending } = useSignStructuredMessage();
+
+// Callback style
+signStructuredMessage({
+  domain: tupleCV({
+    name: stringAsciiCV('MyApp'),
+    version: stringAsciiCV('1.0'),
+    'chain-id': uintCV(1),
+  }),
+  message: tupleCV({
+    action: stringAsciiCV('authorize'),
+    amount: uintCV(1000),
+  }),
+}, {
+  onSuccess: ({ publicKey, signature }) => {},
+  onError: (error) => {},
+});
+
+// Async style
+const { publicKey, signature } = await signStructuredMessageAsync({
+  domain: tupleCV({ ... }),
+  message: tupleCV({ ... }),
+});
+```
+
 ### `useTransferSTX()`
 
 ```ts
@@ -224,6 +264,28 @@ writeContract({
 });
 ```
 
+### `useSignTransaction()`
+
+Sign a serialized transaction without automatically broadcasting it. Useful for sponsored transaction flows where a separate service pays the fee.
+
+> **Note:** OKX wallet does not support raw transaction signing and will throw an error.
+
+```ts
+const { signTransaction, signTransactionAsync, data, error, isPending } = useSignTransaction();
+
+// Callback style
+signTransaction({ transaction: '0x0100...', broadcast: false }, {
+  onSuccess: ({ transaction, txid }) => {},
+  onError: (error) => {},
+});
+
+// Async style
+const { transaction, txid } = await signTransactionAsync({
+  transaction: '0x0100...',
+  broadcast: false,
+});
+```
+
 ### `useBnsName()`
 
 ```ts
@@ -255,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;
@@ -752,6 +819,163 @@ var useSignMessage = () => {
     [signMessage, signMessageAsync, reset, data, error, status]
   );
 };
+var useSignStructuredMessage = () => {
+  const { isConnected, provider } = useAddress();
+  const [data, setData] = react.useState(
+    void 0
+  );
+  const [error, setError] = react.useState(null);
+  const [status, setStatus] = react.useState("idle");
+  const signStructuredMessageAsync = react.useCallback(
+    async (variables) => {
+      if (!isConnected) {
+        throw new WalletNotConnectedError();
+      }
+      if (provider === "okx") {
+        throw new UnsupportedMethodError({
+          method: "stx_signStructuredMessage",
+          wallet: "OKX"
+        });
+      }
+      setStatus("pending");
+      setError(null);
+      setData(void 0);
+      try {
+        const result = await connect.request("stx_signStructuredMessage", {
+          message: variables.message,
+          domain: variables.domain
+        });
+        setData(result);
+        setStatus("success");
+        return result;
+      } catch (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;
+      }
+    },
+    [isConnected, provider]
+  );
+  const signStructuredMessage = react.useCallback(
+    (variables, options) => {
+      signStructuredMessageAsync(variables).then((data2) => {
+        options?.onSuccess?.(data2);
+        options?.onSettled?.(data2, null);
+      }).catch((error2) => {
+        options?.onError?.(error2);
+        options?.onSettled?.(void 0, error2);
+      });
+    },
+    [signStructuredMessageAsync]
+  );
+  const reset = react.useCallback(() => {
+    setData(void 0);
+    setError(null);
+    setStatus("idle");
+  }, []);
+  return react.useMemo(
+    () => ({
+      signStructuredMessage,
+      signStructuredMessageAsync,
+      reset,
+      data,
+      error,
+      isError: status === "error",
+      isIdle: status === "idle",
+      isPending: status === "pending",
+      isSuccess: status === "success",
+      status
+    }),
+    [
+      signStructuredMessage,
+      signStructuredMessageAsync,
+      reset,
+      data,
+      error,
+      status
+    ]
+  );
+};
+var useSignTransaction = () => {
+  const { isConnected, provider } = useAddress();
+  const [data, setData] = react.useState(void 0);
+  const [error, setError] = react.useState(null);
+  const [status, setStatus] = react.useState("idle");
+  const signTransactionAsync = react.useCallback(
+    async (variables) => {
+      if (!isConnected) {
+        throw new WalletNotConnectedError();
+      }
+      if (provider === "okx") {
+        throw new UnsupportedMethodError({
+          method: "stx_signTransaction",
+          wallet: "OKX"
+        });
+      }
+      setStatus("pending");
+      setError(null);
+      setData(void 0);
+      try {
+        const result = await connect.request("stx_signTransaction", {
+          transaction: variables.transaction,
+          ...variables.broadcast !== void 0 && {
+            broadcast: variables.broadcast
+          }
+        });
+        setData(result);
+        setStatus("success");
+        return result;
+      } catch (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;
+      }
+    },
+    [isConnected, provider]
+  );
+  const signTransaction = react.useCallback(
+    (variables, options) => {
+      signTransactionAsync(variables).then((data2) => {
+        options?.onSuccess?.(data2);
+        options?.onSettled?.(data2, null);
+      }).catch((error2) => {
+        options?.onError?.(error2);
+        options?.onSettled?.(void 0, error2);
+      });
+    },
+    [signTransactionAsync]
+  );
+  const reset = react.useCallback(() => {
+    setData(void 0);
+    setError(null);
+    setStatus("idle");
+  }, []);
+  return react.useMemo(
+    () => ({
+      signTransaction,
+      signTransactionAsync,
+      reset,
+      data,
+      error,
+      isError: status === "error",
+      isIdle: status === "idle",
+      isPending: status === "pending",
+      isSuccess: status === "success",
+      status
+    }),
+    [signTransaction, signTransactionAsync, reset, data, error, status]
+  );
+};
 
 // src/utils/get-network-from-address.ts
 var getNetworkFromAddress = (address) => {
@@ -773,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);
@@ -781,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",
@@ -816,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;
@@ -1004,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);
@@ -1013,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,
@@ -1048,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;
@@ -1133,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;
@@ -1144,6 +1381,8 @@ exports.useBnsName = useBnsName;
 exports.useConnect = useConnect;
 exports.useDisconnect = useDisconnect;
 exports.useSignMessage = useSignMessage;
+exports.useSignStructuredMessage = useSignStructuredMessage;
+exports.useSignTransaction = useSignTransaction;
 exports.useTransferSTX = useTransferSTX;
 exports.useWallets = useWallets;
 exports.useWriteContract = useWriteContract;