@satoshai/kit 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PostCondition, PostConditionMode, ClarityValue } from '@stacks/transactions';
+import { ClarityAbi, ExtractAbiFunctionNames, Pretty, ExtractAbiFunction, ClarityAbiArgToPrimitiveTypeValue } from 'clarity-abitype';
+export { ClarityAbi } from 'clarity-abitype';
 
 declare const SUPPORTED_STACKS_WALLETS: readonly ["xverse", "leather", "asigna", "fordefi", "wallet-connect", "okx"];
 type SupportedStacksWallet = (typeof SUPPORTED_STACKS_WALLETS)[number];
@@ -122,26 +124,82 @@ declare const useSignMessage: () => {
     status: MutationStatus;
 };
 
+interface TransferSTXVariables {
+    recipient: string;
+    amount: bigint | number | string;
+    memo?: string;
+    fee?: bigint | number | string;
+    nonce?: bigint | number | string;
+}
+interface TransferSTXOptions {
+    onSuccess?: (txid: string) => void;
+    onError?: (error: Error) => void;
+    onSettled?: (txid: string | undefined, error: Error | null) => void;
+}
+declare const useTransferSTX: () => {
+    transferSTX: (variables: TransferSTXVariables, options?: TransferSTXOptions) => void;
+    transferSTXAsync: (variables: TransferSTXVariables) => Promise<string>;
+    reset: () => void;
+    data: string | undefined;
+    error: Error | null;
+    isError: boolean;
+    isIdle: boolean;
+    isPending: boolean;
+    isSuccess: boolean;
+    status: MutationStatus;
+};
+
+/** Contract principal string in the format `address.contract-name` */
+type TraitReference = `${string}.${string}`;
+/** Union of public function names from a Clarity ABI */
+type PublicFunctionName<TAbi extends ClarityAbi> = ExtractAbiFunctionNames<TAbi, 'public'>;
+/** Named args object for a specific public function, derived from ABI */
+type PublicFunctionArgs<TAbi extends ClarityAbi, TFn extends ExtractAbiFunctionNames<TAbi, 'public'>> = Pretty<{
+    [K in ExtractAbiFunction<TAbi, TFn, 'public'>['args'][number] as K['name']]: ClarityAbiArgToPrimitiveTypeValue<K>;
+}>;
+
 interface PostConditionConfig {
     postConditions: PostCondition[];
     mode: PostConditionMode;
 }
-interface WriteContractVariables {
+/** Typed mode: ABI present, args is a named object with autocomplete. */
+interface TypedWriteContractVariables<TAbi extends ClarityAbi, TFn extends ExtractAbiFunctionNames<TAbi, 'public'>> {
+    abi: TAbi;
+    address: string;
+    contract: string;
+    functionName: TFn;
+    args: PublicFunctionArgs<TAbi, TFn>;
+    pc: PostConditionConfig;
+}
+/** Untyped mode: no ABI, args is ClarityValue[] (original behavior). */
+interface UntypedWriteContractVariables {
     address: string;
     contract: string;
     functionName: string;
     args: ClarityValue[];
     pc: PostConditionConfig;
 }
+/** Backward-compatible alias for the untyped variant. */
+type WriteContractVariables = UntypedWriteContractVariables;
 interface WriteContractOptions {
     onSuccess?: (txHash: string) => void;
     onError?: (error: Error) => void;
     onSettled?: (txHash: string | undefined, error: Error | null) => void;
 }
+/** Overloaded async function: typed mode (with ABI) or untyped mode. */
+interface WriteContractAsyncFn {
+    <const TAbi extends ClarityAbi, TFn extends ExtractAbiFunctionNames<TAbi, 'public'>>(variables: TypedWriteContractVariables<TAbi, TFn>): Promise<string>;
+    (variables: UntypedWriteContractVariables): Promise<string>;
+}
+/** Overloaded fire-and-forget function: typed mode or untyped mode. */
+interface WriteContractFn {
+    <const TAbi extends ClarityAbi, TFn extends ExtractAbiFunctionNames<TAbi, 'public'>>(variables: TypedWriteContractVariables<TAbi, TFn>, options?: WriteContractOptions): void;
+    (variables: UntypedWriteContractVariables, options?: WriteContractOptions): void;
+}
 
 declare const useWriteContract: () => {
-    writeContract: (variables: WriteContractVariables, options?: WriteContractOptions) => void;
-    writeContractAsync: (variables: WriteContractVariables) => Promise<string>;
+    writeContract: WriteContractFn;
+    writeContractAsync: WriteContractAsyncFn;
     reset: () => void;
     data: string | undefined;
     error: Error | null;
@@ -174,4 +232,15 @@ interface StacksWallets {
 }
 declare const getStacksWallets: () => StacksWallets;
 
-export { type ConnectOptions, type MutationStatus, type PostConditionConfig, SUPPORTED_STACKS_WALLETS, type SignMessageData, type SignMessageOptions, type SignMessageVariables, type StacksChain, StacksWalletProvider, type StacksWallets, type SupportedStacksWallet, type WalletConnectMetadata, type WalletContextValue, type WalletInfo, type WalletState, type WriteContractOptions, type WriteContractVariables, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useWallets, useWriteContract };
+/** Pre-bind ABI + address + contract for reuse with useWriteContract. */
+declare function createContractConfig<const TAbi extends ClarityAbi>(config: {
+    abi: TAbi;
+    address: string;
+    contract: string;
+}): {
+    abi: TAbi;
+    address: string;
+    contract: string;
+};
+
+export { type ConnectOptions, type MutationStatus, type PostConditionConfig, type PublicFunctionArgs, type PublicFunctionName, SUPPORTED_STACKS_WALLETS, type SignMessageData, type SignMessageOptions, type SignMessageVariables, type StacksChain, StacksWalletProvider, type StacksWallets, type SupportedStacksWallet, type TraitReference, type TransferSTXOptions, type TransferSTXVariables, type TypedWriteContractVariables, type UntypedWriteContractVariables, type WalletConnectMetadata, type WalletContextValue, type WalletInfo, type WalletState, type WriteContractOptions, type WriteContractVariables, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useTransferSTX, useWallets, useWriteContract };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { WalletConnect, DEFAULT_PROVIDERS, WALLET_CONNECT_PROVIDER, clearSelectedProviderId, request, getSelectedProviderId, getSelectedProvider, setSelectedProviderId } from '@stacks/connect';
 import { createContext, useState, useRef, useEffect, useCallback, useMemo, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
-import { PostConditionMode, postConditionToHex, cvToHex } from '@stacks/transactions';
+import { PostConditionMode, postConditionToHex, cvToHex, noneCV, contractPrincipalCV, standardPrincipalCV, boolCV, intCV, uintCV, bufferCV, stringAsciiCV, stringUtf8CV, someCV, listCV, tupleCV } from '@stacks/transactions';
 import { getPrimaryName } from 'bns-v2-sdk';
 
 // src/constants/stacks-provider-mapping.ts
@@ -284,6 +284,7 @@ var StacksWalletProvider = ({
   const [provider, setProvider] = useState();
   const [isConnecting, setIsConnecting] = useState(false);
   const connectGenRef = useRef(0);
+  const wasConnectedRef = useRef(false);
   const wcInitRef = useRef(null);
   const walletConnectRef = useRef(walletConnect);
   walletConnectRef.current = walletConnect;
@@ -507,8 +508,11 @@ var StacksWalletProvider = ({
     );
   }, [address, provider]);
   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 = useCallback(
     (newAddress) => {
@@ -757,10 +761,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] = useState(void 0);
+  const [error, setError] = useState(null);
+  const [status, setStatus] = useState("idle");
+  const transferSTXAsync = 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 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 = 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 = useCallback(() => {
+    setData(void 0);
+    setError(null);
+    setStatus("idle");
+  }, []);
+  return 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 uintCV(value);
+      }
+      case "int128": {
+        if (typeof value !== "bigint") {
+          throw new Error(
+            `@satoshai/kit: Expected bigint (int128), got ${typeof value}`
+          );
+        }
+        return intCV(value);
+      }
+      case "bool": {
+        if (typeof value !== "boolean") {
+          throw new Error(
+            `@satoshai/kit: Expected boolean (bool), got ${typeof value}`
+          );
+        }
+        return 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 contractPrincipalCV(addr, rest.join("."));
+        }
+        return standardPrincipalCV(value);
+      }
+      case "none":
+        return 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 bufferCV(value);
+  }
+  if ("string-ascii" in abiType) {
+    if (typeof value !== "string") {
+      throw new Error(
+        `@satoshai/kit: Expected string (string-ascii), got ${typeof value}`
+      );
+    }
+    return stringAsciiCV(value);
+  }
+  if ("string-utf8" in abiType) {
+    if (typeof value !== "string") {
+      throw new Error(
+        `@satoshai/kit: Expected string (string-utf8), got ${typeof value}`
+      );
+    }
+    return stringUtf8CV(value);
+  }
+  if ("optional" in abiType) {
+    if (value === null || value === void 0) return noneCV();
+    return 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 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 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) => postConditionToHex(pc));
 var prepareArgsForOKX = (args) => args.map((arg) => 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] = useState(void 0);
@@ -774,6 +1007,7 @@ var useWriteContract = () => {
       setStatus("pending");
       setError(null);
       setData(void 0);
+      const resolvedArgs = resolveArgs(variables);
       try {
         if (provider === "okx") {
           if (!window.okxwallet) {
@@ -783,7 +1017,7 @@ var useWriteContract = () => {
             contractAddress: variables.address,
             contractName: variables.contract,
             functionName: variables.functionName,
-            functionArgs: prepareArgsForOKX(variables.args),
+            functionArgs: prepareArgsForOKX(resolvedArgs),
             postConditions: preparePostConditionsForOKX(
               variables.pc.postConditions
             ),
@@ -800,7 +1034,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 === PostConditionMode.Allow ? "allow" : "deny",
           network: getNetworkFromAddress(address)
@@ -862,20 +1096,28 @@ var useBnsName = (address) => {
       setIsLoading(false);
       return;
     }
+    let cancelled = false;
     const fetchBnsName = async () => {
       setIsLoading(true);
       try {
         const network = getNetworkFromAddress(address);
         const result = await 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 };
 };
@@ -884,6 +1126,11 @@ var useWallets = () => {
   return useMemo(() => ({ wallets }), [wallets]);
 };
 
-export { SUPPORTED_STACKS_WALLETS, StacksWalletProvider, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useWallets, useWriteContract };
+// src/utils/create-contract-config.ts
+function createContractConfig(config) {
+  return config;
+}
+
+export { SUPPORTED_STACKS_WALLETS, StacksWalletProvider, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useTransferSTX, useWallets, useWriteContract };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map