feat: add useSignStructuredMessage hook (#41)

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

Author: satoshai-dev

.changeset/use-sign-structured-message.md

@@ -0,0 +1,5 @@
+---
+"@satoshai/kit": minor
+---
+
+Add `useSignStructuredMessage` hook for SIP-018 structured data signing via `stx_signStructuredMessage`.

examples/vite-react/src/app.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import { PostConditionMode, makeUnsignedSTXTokenTransfer, AnchorMode } from '@stacks/transactions';
+import { PostConditionMode, makeUnsignedSTXTokenTransfer, AnchorMode, tupleCV, stringAsciiCV, uintCV } from '@stacks/transactions';
 import {
     StacksWalletProvider,
     useAddress,
@@ -11,6 +11,7 @@ import {
     useTransferSTX,
     useSignTransaction,
     createContractConfig,
+    useSignStructuredMessage,
 } from '@satoshai/kit';
 
 const wcProjectId = import.meta.env.VITE_WALLETCONNECT_PROJECT_ID as string | undefined;
@@ -102,6 +103,7 @@ const Wallet = ({ useModal }: { useModal: boolean }) => {
                     </p>
                 ) : null}
                 <TransferSTXDemo />
+                <SignStructuredMessageDemo />
                 <WriteContractDemo address={address} />
                 <SignTransactionDemo address={address} />
                 <button onClick={() => disconnect()}>Disconnect</button>
@@ -215,6 +217,51 @@ const TransferSTXDemo = () => {
     );
 };
 
+// Demonstrates useSignStructuredMessage hook (SIP-018)
+const SignStructuredMessageDemo = () => {
+    const { signStructuredMessage, isPending, isSuccess, isError, data, error, reset } =
+        useSignStructuredMessage();
+
+    const handleSign = () => {
+        signStructuredMessage(
+            {
+                domain: tupleCV({
+                    name: stringAsciiCV('ExampleApp'),
+                    version: stringAsciiCV('1.0'),
+                    'chain-id': uintCV(1),
+                }),
+                message: tupleCV({
+                    action: stringAsciiCV('authorize'),
+                    amount: uintCV(1000),
+                }),
+            },
+            {
+                onSuccess: (result) => console.log('Structured message signed:', result.signature),
+                onError: (err) => console.error('Structured message signing failed:', err),
+            }
+        );
+    };
+
+    return (
+        <div style={{ marginTop: '1rem', marginBottom: '1rem' }}>
+            <h3>Sign Structured Message (SIP-018)</h3>
+            <button onClick={handleSign} disabled={isPending}>
+                {isPending ? 'Signing...' : 'Sign Structured Message'}
+            </button>
+            {isSuccess && (
+                <p style={{ color: 'green' }}>
+                    Signature: {data?.signature.slice(0, 20)}... <button onClick={reset}>Clear</button>
+                </p>
+            )}
+            {isError && (
+                <p style={{ color: 'red' }}>
+                    Error: {error?.message} <button onClick={reset}>Clear</button>
+                </p>
+            )}
+        </div>
+    );
+};
+
 // Demonstrates useSignTransaction hook
 const SignTransactionDemo = ({ address }: { address: string }) => {
     const [broadcast, setBroadcast] = useState(false);

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
+- **`useSignStructuredMessage`** — Sign SIP-018 structured data
 - **`useSignTransaction`** — Sign serialized transactions (sponsored tx flows)
 - **`useWriteContract`** — Call smart contracts with post-conditions
 - **`useTransferSTX`** — Native STX transfers
@@ -181,6 +182,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

packages/kit/src/hooks/use-sign-structured-message.ts

@@ -0,0 +1,121 @@
+'use client';
+
+import { request } from '@stacks/connect';
+import type { ClarityValue, TupleCV } from '@stacks/transactions';
+import { useCallback, useMemo, useState } from 'react';
+
+import type { MutationStatus } from '../provider/stacks-wallet-provider.types';
+import { useAddress } from './use-address';
+
+export interface SignStructuredMessageVariables {
+    message: ClarityValue;
+    domain: TupleCV;
+}
+
+export interface SignStructuredMessageData {
+    publicKey: string;
+    signature: string;
+}
+
+export interface SignStructuredMessageOptions {
+    onSuccess?: (data: SignStructuredMessageData) => void;
+    onError?: (error: Error) => void;
+    onSettled?: (
+        data: SignStructuredMessageData | undefined,
+        error: Error | null
+    ) => void;
+}
+
+export const useSignStructuredMessage = () => {
+    const { isConnected, provider } = useAddress();
+    const [data, setData] = useState<SignStructuredMessageData | undefined>(
+        undefined
+    );
+    const [error, setError] = useState<Error | null>(null);
+    const [status, setStatus] = useState<MutationStatus>('idle');
+
+    const signStructuredMessageAsync = useCallback(
+        async (
+            variables: SignStructuredMessageVariables
+        ): Promise<SignStructuredMessageData> => {
+            if (!isConnected) {
+                throw new Error('Wallet is not connected');
+            }
+
+            if (provider === 'okx') {
+                throw new Error(
+                    'Structured message signing is not supported by OKX wallet'
+                );
+            }
+
+            setStatus('pending');
+            setError(null);
+            setData(undefined);
+
+            try {
+                const result = await request('stx_signStructuredMessage', {
+                    message: variables.message,
+                    domain: variables.domain,
+                });
+
+                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 signStructuredMessage = useCallback(
+        (
+            variables: SignStructuredMessageVariables,
+            options?: SignStructuredMessageOptions
+        ) => {
+            signStructuredMessageAsync(variables)
+                .then((data) => {
+                    options?.onSuccess?.(data);
+                    options?.onSettled?.(data, null);
+                })
+                .catch((error) => {
+                    options?.onError?.(error);
+                    options?.onSettled?.(undefined, error);
+                });
+        },
+        [signStructuredMessageAsync]
+    );
+
+    const reset = useCallback(() => {
+        setData(undefined);
+        setError(null);
+        setStatus('idle');
+    }, []);
+
+    return 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,
+        ]
+    );
+};

packages/kit/src/index.ts

@@ -11,6 +11,12 @@ export {
     type SignMessageData,
     type SignMessageOptions,
 } from './hooks/use-sign-message';
+export {
+    useSignStructuredMessage,
+    type SignStructuredMessageVariables,
+    type SignStructuredMessageData,
+    type SignStructuredMessageOptions,
+} from './hooks/use-sign-structured-message';
 export {
     useSignTransaction,
     type SignTransactionVariables,