feat: add useSignTransaction hook (#42)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: satoshai-dev

.changeset/use-sign-transaction.md

@@ -0,0 +1,5 @@
+---
+"@satoshai/kit": minor
+---
+
+Add `useSignTransaction` hook for signing transactions without broadcasting via `stx_signTransaction`. Enables sponsored transaction flows.

examples/vite-react/src/app.tsx

@@ -9,6 +9,7 @@ import {
     useWallets,
     useWriteContract,
     useTransferSTX,
+    useSignTransaction,
     createContractConfig,
 } from '@satoshai/kit';
 
@@ -102,6 +103,7 @@ const Wallet = ({ useModal }: { useModal: boolean }) => {
                 ) : null}
                 <TransferSTXDemo />
                 <WriteContractDemo address={address} />
+                <SignTransactionDemo />
                 <button onClick={() => disconnect()}>Disconnect</button>
             </div>
         );
@@ -213,6 +215,63 @@ const TransferSTXDemo = () => {
     );
 };
 
+// Demonstrates useSignTransaction hook
+const SignTransactionDemo = () => {
+    const [transaction, setTransaction] = useState('');
+    const [broadcast, setBroadcast] = useState(false);
+    const { signTransaction, isPending, isSuccess, isError, data, error, reset } = useSignTransaction();
+
+    const handleSign = () => {
+        if (!transaction) return;
+        signTransaction(
+            { transaction, broadcast },
+            {
+                onSuccess: (result) => console.log('Transaction signed:', result),
+                onError: (err) => console.error('Transaction signing failed:', err),
+            }
+        );
+    };
+
+    return (
+        <div style={{ marginTop: '1rem', marginBottom: '1rem' }}>
+            <h3>Sign Transaction</h3>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem', maxWidth: '400px' }}>
+                <input
+                    type="text"
+                    placeholder="Serialized transaction hex"
+                    value={transaction}
+                    onChange={(e) => setTransaction(e.target.value)}
+                    disabled={isPending}
+                />
+                <label style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+                    <input
+                        type="checkbox"
+                        checked={broadcast}
+                        onChange={(e) => setBroadcast(e.target.checked)}
+                        disabled={isPending}
+                    />
+                    Broadcast
+                </label>
+                <button onClick={handleSign} disabled={isPending || !transaction}>
+                    {isPending ? 'Signing...' : 'Sign Transaction'}
+                </button>
+            </div>
+            {isSuccess && data && (
+                <div style={{ color: 'green' }}>
+                    <p>Signed TX: {data.transaction}</p>
+                    {data.txid && <p>TXID: {data.txid}</p>}
+                    <button onClick={reset}>Clear</button>
+                </div>
+            )}
+            {isError && (
+                <p style={{ color: 'red' }}>
+                    Error: {error?.message} <button onClick={reset}>Clear</button>
+                </p>
+            )}
+        </div>
+    );
+};
+
 // Demonstrates typed useWriteContract with ABI inference
 const WriteContractDemo = ({ address }: { address: string }) => {
     const { writeContract, isPending, isSuccess, isError, data, error } = useWriteContract();

packages/kit/README.md

@@ -9,6 +9,7 @@ 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
+- **`useSignTransaction`** — Sign serialized transactions (sponsored tx flows)
 - **`useWriteContract`** — Call smart contracts with post-conditions
 - **`useTransferSTX`** — Native STX transfers
 - **`useBnsName`** — Resolve BNS v2 names
@@ -224,6 +225,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

packages/kit/src/hooks/use-sign-transaction.ts

@@ -0,0 +1,113 @@
+'use client';
+
+import { request } from '@stacks/connect';
+import { useCallback, useMemo, useState } from 'react';
+
+import type { MutationStatus } from '../provider/stacks-wallet-provider.types';
+import { useAddress } from './use-address';
+
+export interface SignTransactionVariables {
+    transaction: string;
+    broadcast?: boolean;
+}
+
+export interface SignTransactionData {
+    transaction: string;
+    txid?: string;
+}
+
+export interface SignTransactionOptions {
+    onSuccess?: (data: SignTransactionData) => void;
+    onError?: (error: Error) => void;
+    onSettled?: (
+        data: SignTransactionData | undefined,
+        error: Error | null
+    ) => void;
+}
+
+export const useSignTransaction = () => {
+    const { isConnected, provider } = useAddress();
+    const [data, setData] = useState<SignTransactionData | undefined>(undefined);
+    const [error, setError] = useState<Error | null>(null);
+    const [status, setStatus] = useState<MutationStatus>('idle');
+
+    const signTransactionAsync = useCallback(
+        async (
+            variables: SignTransactionVariables
+        ): Promise<SignTransactionData> => {
+            if (!isConnected) {
+                throw new Error('Wallet is not connected');
+            }
+
+            if (provider === 'okx') {
+                throw new Error(
+                    'Transaction signing is not supported by OKX wallet'
+                );
+            }
+
+            setStatus('pending');
+            setError(null);
+            setData(undefined);
+
+            try {
+                const result = await request('stx_signTransaction', {
+                    transaction: variables.transaction,
+                    ...(variables.broadcast !== undefined && {
+                        broadcast: variables.broadcast,
+                    }),
+                });
+
+                setData(result);
+                setStatus('success');
+                return result;
+            } catch (err) {
+                const error =
+                    err instanceof Error ? err : new Error(String(err));
+                setError(error);
+                setStatus('error');
+                throw error;
+            }
+        },
+        [isConnected, provider]
+    );
+
+    const signTransaction = useCallback(
+        (
+            variables: SignTransactionVariables,
+            options?: SignTransactionOptions
+        ) => {
+            signTransactionAsync(variables)
+                .then((data) => {
+                    options?.onSuccess?.(data);
+                    options?.onSettled?.(data, null);
+                })
+                .catch((error) => {
+                    options?.onError?.(error);
+                    options?.onSettled?.(undefined, error);
+                });
+        },
+        [signTransactionAsync]
+    );
+
+    const reset = useCallback(() => {
+        setData(undefined);
+        setError(null);
+        setStatus('idle');
+    }, []);
+
+    return 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]
+    );
+};

packages/kit/src/index.ts

@@ -11,6 +11,12 @@ export {
     type SignMessageData,
     type SignMessageOptions,
 } from './hooks/use-sign-message';
+export {
+    useSignTransaction,
+    type SignTransactionVariables,
+    type SignTransactionData,
+    type SignTransactionOptions,
+} from './hooks/use-sign-transaction';
 export {
     useTransferSTX,
     type TransferSTXVariables,