@satoshai/kit 0.4.0 → 0.5.0

package/README.md

@@ -10,6 +10,7 @@ Typesafe Stacks wallet & contract interaction library for React. Wagmi-inspired
 - **`useAddress`** — Access connected wallet address and status
 - **`useSignMessage`** — Sign arbitrary messages
 - **`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 +180,28 @@ signMessage({ message: 'Hello Stacks' }, {
 const { publicKey, signature } = await signMessageAsync({ message: 'Hello Stacks' });
 ```
 
+### `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

package/dist/index.cjs

@@ -286,6 +286,7 @@ var StacksWalletProvider = ({
   const [provider, setProvider] = react.useState();
   const [isConnecting, setIsConnecting] = react.useState(false);
   const connectGenRef = react.useRef(0);
+  const wasConnectedRef = react.useRef(false);
   const wcInitRef = react.useRef(null);
   const walletConnectRef = react.useRef(walletConnect);
   walletConnectRef.current = walletConnect;
@@ -509,8 +510,11 @@ var StacksWalletProvider = ({
     );
   }, [address, provider]);
   react.useEffect(() => {
-    if (!address || !provider || !onConnect) return;
-    onConnect(provider, address);
+    const isConnected = !!address && !!provider;
+    if (isConnected && !wasConnectedRef.current) {
+      onConnect?.(provider, address);
+    }
+    wasConnectedRef.current = isConnected;
   }, [address, provider, onConnect]);
   const handleAddressChange = react.useCallback(
     (newAddress) => {
@@ -759,10 +763,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);
@@ -776,6 +1009,7 @@ var useWriteContract = () => {
       setStatus("pending");
       setError(null);
       setData(void 0);
+      const resolvedArgs = resolveArgs(variables);
       try {
         if (provider === "okx") {
           if (!window.okxwallet) {
@@ -785,7 +1019,7 @@ var useWriteContract = () => {
             contractAddress: variables.address,
             contractName: variables.contract,
             functionName: variables.functionName,
-            functionArgs: prepareArgsForOKX(variables.args),
+            functionArgs: prepareArgsForOKX(resolvedArgs),
             postConditions: preparePostConditionsForOKX(
               variables.pc.postConditions
             ),
@@ -802,7 +1036,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)
@@ -864,20 +1098,28 @@ var useBnsName = (address) => {
       setIsLoading(false);
       return;
     }
+    let cancelled = false;
     const fetchBnsName = async () => {
       setIsLoading(true);
       try {
         const network = getNetworkFromAddress(address);
         const result = await bnsV2Sdk.getPrimaryName({ address, network });
+        if (cancelled) return;
         const fullName = result ? `${result.name}.${result.namespace}` : null;
         setBnsName(fullName);
       } catch {
+        if (cancelled) return;
         setBnsName(null);
       } finally {
-        setIsLoading(false);
+        if (!cancelled) {
+          setIsLoading(false);
+        }
       }
     };
     void fetchBnsName();
+    return () => {
+      cancelled = true;
+    };
   }, [address]);
   return { bnsName, isLoading };
 };
@@ -886,8 +1128,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;
@@ -896,6 +1144,7 @@ exports.useBnsName = useBnsName;
 exports.useConnect = useConnect;
 exports.useDisconnect = useDisconnect;
 exports.useSignMessage = useSignMessage;
+exports.useTransferSTX = useTransferSTX;
 exports.useWallets = useWallets;
 exports.useWriteContract = useWriteContract;
 //# sourceMappingURL=index.cjs.map