@satoshai/kit 0.4.1 → 0.6.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,7 +13,10 @@ 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
 - **6 wallets supported** — Xverse, Leather, OKX, Asigna, Fordefi, WalletConnect
 - **Next.js App Router compatible** — `"use client"` directives included
@@ -179,6 +186,62 @@ 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
+const { transferSTX, transferSTXAsync, data, error, isPending } = useTransferSTX();
+
+// Callback style
+transferSTX({
+  recipient: 'SP2...',
+  amount: 1000000n,  // in microSTX
+  memo: 'optional memo',
+}, {
+  onSuccess: (txid) => {},
+  onError: (error) => {},
+});
+
+// Async style
+const txid = await transferSTXAsync({
+  recipient: 'SP2...',
+  amount: 1000000n,
+});
+```
+
 ### `useWriteContract()`
 
 ```ts
@@ -201,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

package/dist/index.cjs

@@ -752,6 +752,153 @@ 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 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(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 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 Error("Wallet is not connected");
+      }
+      if (provider === "okx") {
+        throw new Error(
+          "Transaction signing is not supported by OKX wallet"
+        );
+      }
+      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 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) => {
@@ -763,10 +910,239 @@ var getNetworkFromAddress = (address) => {
   }
   throw new Error(`Invalid Stacks address: ${address}`);
 };
+
+// src/hooks/use-transfer-stx.ts
+var useTransferSTX = () => {
+  const { isConnected, address, provider } = useAddress();
+  const [data, setData] = react.useState(void 0);
+  const [error, setError] = react.useState(null);
+  const [status, setStatus] = react.useState("idle");
+  const transferSTXAsync = react.useCallback(
+    async (variables) => {
+      if (!isConnected || !address) {
+        throw new Error("Wallet is not connected");
+      }
+      setStatus("pending");
+      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({
+            txType: "token_transfer",
+            recipient: variables.recipient,
+            amount: String(variables.amount),
+            memo: variables.memo ?? "",
+            stxAddress: address,
+            anchorMode: 3
+          });
+          setData(response2.txHash);
+          setStatus("success");
+          return response2.txHash;
+        }
+        const response = await connect.request("stx_transferStx", {
+          recipient: variables.recipient,
+          amount: variables.amount,
+          ...variables.memo !== void 0 && {
+            memo: variables.memo
+          },
+          ...variables.fee !== void 0 && {
+            fee: variables.fee
+          },
+          ...variables.nonce !== void 0 && {
+            nonce: variables.nonce
+          },
+          network: getNetworkFromAddress(address)
+        });
+        if (!response.txid) {
+          throw new Error("No transaction ID returned");
+        }
+        setData(response.txid);
+        setStatus("success");
+        return response.txid;
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        setError(error2);
+        setStatus("error");
+        throw error2;
+      }
+    },
+    [isConnected, address, provider]
+  );
+  const transferSTX = react.useCallback(
+    (variables, options) => {
+      transferSTXAsync(variables).then((txid) => {
+        options?.onSuccess?.(txid);
+        options?.onSettled?.(txid, null);
+      }).catch((error2) => {
+        options?.onError?.(error2);
+        options?.onSettled?.(void 0, error2);
+      });
+    },
+    [transferSTXAsync]
+  );
+  const reset = react.useCallback(() => {
+    setData(void 0);
+    setError(null);
+    setStatus("idle");
+  }, []);
+  return react.useMemo(
+    () => ({
+      transferSTX,
+      transferSTXAsync,
+      reset,
+      data,
+      error,
+      isError: status === "error",
+      isIdle: status === "idle",
+      isPending: status === "pending",
+      isSuccess: status === "success",
+      status
+    }),
+    [transferSTX, transferSTXAsync, reset, data, error, status]
+  );
+};
+function toClarityValue(value, abiType) {
+  if (typeof abiType === "string") {
+    switch (abiType) {
+      case "uint128": {
+        if (typeof value !== "bigint") {
+          throw new Error(
+            `@satoshai/kit: Expected bigint (uint128), got ${typeof value}`
+          );
+        }
+        return transactions.uintCV(value);
+      }
+      case "int128": {
+        if (typeof value !== "bigint") {
+          throw new Error(
+            `@satoshai/kit: Expected bigint (int128), got ${typeof value}`
+          );
+        }
+        return transactions.intCV(value);
+      }
+      case "bool": {
+        if (typeof value !== "boolean") {
+          throw new Error(
+            `@satoshai/kit: Expected boolean (bool), got ${typeof value}`
+          );
+        }
+        return transactions.boolCV(value);
+      }
+      case "principal":
+      case "trait_reference": {
+        if (typeof value !== "string") {
+          throw new Error(
+            `@satoshai/kit: Expected string (${abiType}), got ${typeof value}`
+          );
+        }
+        if (value.includes(".")) {
+          const [addr, ...rest] = value.split(".");
+          return transactions.contractPrincipalCV(addr, rest.join("."));
+        }
+        return transactions.standardPrincipalCV(value);
+      }
+      case "none":
+        return transactions.noneCV();
+      default:
+        throw new Error(
+          `@satoshai/kit: Unsupported ABI type "${abiType}"`
+        );
+    }
+  }
+  if ("buffer" in abiType) {
+    if (!(value instanceof Uint8Array)) {
+      throw new Error(
+        `@satoshai/kit: Expected Uint8Array (buffer), got ${typeof value}`
+      );
+    }
+    return transactions.bufferCV(value);
+  }
+  if ("string-ascii" in abiType) {
+    if (typeof value !== "string") {
+      throw new Error(
+        `@satoshai/kit: Expected string (string-ascii), got ${typeof value}`
+      );
+    }
+    return transactions.stringAsciiCV(value);
+  }
+  if ("string-utf8" in abiType) {
+    if (typeof value !== "string") {
+      throw new Error(
+        `@satoshai/kit: Expected string (string-utf8), got ${typeof value}`
+      );
+    }
+    return transactions.stringUtf8CV(value);
+  }
+  if ("optional" in abiType) {
+    if (value === null || value === void 0) return transactions.noneCV();
+    return transactions.someCV(toClarityValue(value, abiType.optional));
+  }
+  if ("list" in abiType) {
+    if (!Array.isArray(value)) {
+      throw new Error(
+        `@satoshai/kit: Expected array (list), got ${typeof value}`
+      );
+    }
+    const listType = abiType.list;
+    return transactions.listCV(
+      value.map((item) => toClarityValue(item, listType.type))
+    );
+  }
+  if ("tuple" in abiType) {
+    if (typeof value !== "object" || value === null) {
+      throw new Error(
+        `@satoshai/kit: Expected object (tuple), got ${value === null ? "null" : typeof value}`
+      );
+    }
+    const entries = abiType.tuple;
+    const obj = value;
+    const result = {};
+    for (const entry of entries) {
+      result[entry.name] = toClarityValue(obj[entry.name], entry.type);
+    }
+    return transactions.tupleCV(result);
+  }
+  throw new Error(
+    `@satoshai/kit: Unsupported ABI type: ${JSON.stringify(abiType)}`
+  );
+}
+function namedArgsToClarityValues(args, abiArgs) {
+  return abiArgs.map((abiArg) => {
+    if (!(abiArg.name in args)) {
+      throw new Error(
+        `@satoshai/kit: Missing argument "${abiArg.name}"`
+      );
+    }
+    return toClarityValue(
+      args[abiArg.name],
+      abiArg.type
+    );
+  });
+}
 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
+function resolveArgs(variables) {
+  if (!variables.abi) {
+    return variables.args;
+  }
+  const fn = variables.abi.functions.find(
+    (f) => f.name === variables.functionName && f.access === "public"
+  );
+  if (!fn) {
+    throw new Error(
+      `@satoshai/kit: Public function "${variables.functionName}" not found in ABI`
+    );
+  }
+  return namedArgsToClarityValues(
+    variables.args,
+    fn.args
+  );
+}
 var useWriteContract = () => {
   const { isConnected, address, provider } = useAddress();
   const [data, setData] = react.useState(void 0);
@@ -780,6 +1156,7 @@ var useWriteContract = () => {
       setStatus("pending");
       setError(null);
       setData(void 0);
+      const resolvedArgs = resolveArgs(variables);
       try {
         if (provider === "okx") {
           if (!window.okxwallet) {
@@ -789,7 +1166,7 @@ var useWriteContract = () => {
             contractAddress: variables.address,
             contractName: variables.contract,
             functionName: variables.functionName,
-            functionArgs: prepareArgsForOKX(variables.args),
+            functionArgs: prepareArgsForOKX(resolvedArgs),
             postConditions: preparePostConditionsForOKX(
               variables.pc.postConditions
             ),
@@ -806,7 +1183,7 @@ var useWriteContract = () => {
           address,
           contract: `${variables.address}.${variables.contract}`,
           functionName: variables.functionName,
-          functionArgs: variables.args,
+          functionArgs: resolvedArgs,
           postConditions: variables.pc.postConditions,
           postConditionMode: variables.pc.mode === transactions.PostConditionMode.Allow ? "allow" : "deny",
           network: getNetworkFromAddress(address)
@@ -898,8 +1275,14 @@ var useWallets = () => {
   return react.useMemo(() => ({ wallets }), [wallets]);
 };
 
+// src/utils/create-contract-config.ts
+function createContractConfig(config) {
+  return config;
+}
+
 exports.SUPPORTED_STACKS_WALLETS = SUPPORTED_STACKS_WALLETS;
 exports.StacksWalletProvider = StacksWalletProvider;
+exports.createContractConfig = createContractConfig;
 exports.getLocalStorageWallet = getLocalStorageWallet;
 exports.getNetworkFromAddress = getNetworkFromAddress;
 exports.getStacksWallets = getStacksWallets;
@@ -908,6 +1291,9 @@ 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;
 //# sourceMappingURL=index.cjs.map