diff --git a/docs/react.md b/docs/react.md index 84f3a43..530b15f 100644 --- a/docs/react.md +++ b/docs/react.md @@ -77,7 +77,7 @@ import { useMetamask } from "@thirdweb-dev/react" ``` | | [useMintNFT(contract)](./react.usemintnft.md) | (BETA) Use this to mint a new NFT on your [NFTContract](./react.nftcontract.md) | -| [useMintToken(contract)](./react.useminttoken.md) | (BETA) Use this to mint a new NFT on your ERC20 contract | +| [useMintToken(contract)](./react.useminttoken.md) | (BETA) Use this to mint new tokens on your contract | | [useMultiwrap(contractAddress)](./react.usemultiwrap.md) | Hook for getting an instance of an Multiwrap contract. This contract is an ERC721 in which you can wrap ERC721, ERC1155 and ERC20 tokens. | | [useNetwork()](./react.usenetwork.md) | Hook for getting metadata about the network the current wallet is connected to and switching networks | | [useNetworkMismatch()](./react.usenetworkmismatch.md) |

Hook for checking whether the connected wallet is on the correct network specified by the desiredChainId passed to the <ThirdwebProvider />.

@@ -103,10 +103,12 @@ import { useNetworkMistmatch } from "@thirdweb-dev/react" | [useSignatureDrop(contractAddress)](./react.usesignaturedrop.md) | Hook for getting an instance of an SignatureDrop contract. This contract is meant to interface with ERC721 compliant NFTs that can be lazily minted. | | [useSplit(contractAddress)](./react.usesplit.md) | Hook for getting an instance of a Split contract. This contract supports fund distribution to multiple parties. | | [useToken(contractAddress)](./react.usetoken.md) | Hook for getting an instance of an Token contract. This contract supports ERC20 compliant tokens. | -| [useTokenBalance(contract, walletAddress)](./react.usetokenbalance.md) | (BETA) Use this to get the balance of your Token contract for a given address. | -| [useTokenSupply(contract)](./react.usetokensupply.md) | (BETA) Use this to get a the total supply of your Token contract. | +| [useTokenBalance(contract, walletAddress)](./react.usetokenbalance.md) | (BETA) Use this to get the balance of your contract for a given address. | +| [useTokenSupply(contract)](./react.usetokensupply.md) | (BETA) Use this to get a the total supply of your contract. | | [useTotalCirculatingSupply(\[contract, tokenId\])](./react.usetotalcirculatingsupply.md) |

(BETA) Use this to get a the total (minted) supply of your [NFTContract](./react.nftcontract.md).

\*

| | [useTotalCount(contract)](./react.usetotalcount.md) | (BETA) Use this to get a the number of tokens in your [NFTContract](./react.nftcontract.md). | +| [useTransferBatchToken(contract)](./react.usetransferbatchtoken.md) | (BETA) Use this to transfer batch tokens on your contract | +| [useTransferToken(contract)](./react.usetransfertoken.md) | (BETA) Use this to transfer tokens on your contract | | [useUnclaimedNFTs(contract, queryParams)](./react.useunclaimednfts.md) | (BETA) Use this to get a list of \*unclaimed\* NFT tokens of your ERC721 Drop contract. | | [useUnclaimedNFTSupply(contract)](./react.useunclaimednftsupply.md) | | | [useUpdateMetadata(contract)](./react.useupdatemetadata.md) | (BETA) Use this to update the metadata of your | @@ -159,7 +161,7 @@ import { useWalletConnect } from "@thirdweb-dev/react" | [NFT](./react.nft.md) | (BETA) A single NFT token | | [NFTContract](./react.nftcontract.md) | (BETA) The possible NFT contract types. | | [RequiredParam](./react.requiredparam.md) | (BETA) Makes a parameter required to be passed, but still allowes it to be undefined. | -| [TokenMintParams](./react.tokenmintparams.md) | (BETA) The parameters to pass to the nft mint function. | +| [TokenParams](./react.tokenparams.md) | (BETA) The parameters to pass to the mint and transfer functions. | | [useNFTBalanceParams](./react.usenftbalanceparams.md) | (BETA) The params to pass to useNftBalance. | | [useTotalCirculatingSupplyParams](./react.usetotalcirculatingsupplyparams.md) | (BETA) The params to pass to useTotalCirculatingSupply. | | [WalletAddress](./react.walletaddress.md) | (BETA) A wallet address. | diff --git a/docs/react.tokenmintparams.md b/docs/react.tokenparams.md similarity index 71% rename from docs/react.tokenmintparams.md rename to docs/react.tokenparams.md index 1f24d64..0034cea 100644 --- a/docs/react.tokenmintparams.md +++ b/docs/react.tokenparams.md @@ -1,18 +1,18 @@ -[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [TokenMintParams](./react.tokenmintparams.md) +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [TokenParams](./react.tokenparams.md) -## TokenMintParams type +## TokenParams type > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > -The parameters to pass to the nft mint function. +The parameters to pass to the mint and transfer functions. Signature: ```typescript -export declare type TokenMintParams = { +export declare type TokenParams = { to: WalletAddress; amount: string | number; }; diff --git a/docs/react.useclaimtoken.md b/docs/react.useclaimtoken.md index 5422ce9..ae701b2 100644 --- a/docs/react.useclaimtoken.md +++ b/docs/react.useclaimtoken.md @@ -48,7 +48,7 @@ const Component = () => { return ( diff --git a/docs/react.useminttoken.md b/docs/react.useminttoken.md index ccef132..08621c2 100644 --- a/docs/react.useminttoken.md +++ b/docs/react.useminttoken.md @@ -7,7 +7,7 @@ > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > -Use this to mint a new NFT on your ERC20 contract +Use this to mint new tokens on your contract Signature: @@ -15,7 +15,7 @@ Use this to mint a new NFT on your ERC20 contract export declare function useMintToken(contract: RequiredParam): import("@tanstack/react-query").UseMutationResult Promise; -}, "data">, unknown, TokenMintParams, unknown>; +}, "data">, unknown, TokenParams, unknown>; ``` ## Parameters @@ -26,7 +26,7 @@ export declare function useMintToken(contract: RequiredParam): import("@t Returns: -import("@tanstack/react-query").UseMutationResult<Omit<{ receipt: import("@ethersproject/abstract-provider").TransactionReceipt; data: () => Promise<unknown>; }, "data">, unknown, [TokenMintParams](./react.tokenmintparams.md), unknown> +import("@tanstack/react-query").UseMutationResult<Omit<{ receipt: import("@ethersproject/abstract-provider").TransactionReceipt; data: () => Promise<unknown>; }, "data">, unknown, [TokenParams](./react.tokenparams.md), unknown> a mutation object that can be used to mint a new NFT token to the connected wallet @@ -36,19 +36,19 @@ a mutation object that can be used to mint a new NFT token to the connected wall ```jsx const Component = () => { const { - mutate: mintNft, + mutate: mintTokens, isLoading, error, } = useMintToken(">>YourERC20ContractInstance<<"); if (error) { - console.error("failed to mint nft", error); + console.error("failed to mint tokens", error); } return ( diff --git a/docs/react.usetokenbalance.md b/docs/react.usetokenbalance.md index 809ac21..80bd951 100644 --- a/docs/react.usetokenbalance.md +++ b/docs/react.usetokenbalance.md @@ -7,7 +7,7 @@ > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > -Use this to get the balance of your Token contract for a given address. +Use this to get the balance of your contract for a given address. Signature: diff --git a/docs/react.usetokensupply.md b/docs/react.usetokensupply.md index d4e7887..a2aef55 100644 --- a/docs/react.usetokensupply.md +++ b/docs/react.usetokensupply.md @@ -7,7 +7,7 @@ > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > -Use this to get a the total supply of your Token contract. +Use this to get a the total supply of your contract. Signature: diff --git a/docs/react.usetransferbatchtoken.md b/docs/react.usetransferbatchtoken.md new file mode 100644 index 0000000..4f18995 --- /dev/null +++ b/docs/react.usetransferbatchtoken.md @@ -0,0 +1,55 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [useTransferBatchToken](./react.usetransferbatchtoken.md) + +## useTransferBatchToken() function + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Use this to transfer batch tokens on your contract + +Signature: + +```typescript +export declare function useTransferBatchToken(contract: RequiredParam): import("@tanstack/react-query").UseMutationResult; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| contract | [RequiredParam](./react.requiredparam.md)<Erc20> | an instance of a contract that extends the ERC20 spec (token, token drop, custom contract that follows the ERC20 spec) | + +Returns: + +import("@tanstack/react-query").UseMutationResult<void, unknown, [TokenParams](./react.tokenparams.md)\[\], unknown> + +a mutation object that can be used to mint a new NFT token to the connected wallet + +## Example + + +```jsx +const Component = () => { + const { + mutate: transferBatchTokens, + isLoading, + error, + } = useTransferToken(">>YourERC20ContractInstance<<"); + + if (error) { + console.error("failed to transfer batch tokens", error); + } + + return ( + + ); +}; +``` + diff --git a/docs/react.usetransfertoken.md b/docs/react.usetransfertoken.md new file mode 100644 index 0000000..d875a28 --- /dev/null +++ b/docs/react.usetransfertoken.md @@ -0,0 +1,58 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [useTransferToken](./react.usetransfertoken.md) + +## useTransferToken() function + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Use this to transfer tokens on your contract + +Signature: + +```typescript +export declare function useTransferToken(contract: RequiredParam): import("@tanstack/react-query").UseMutationResult Promise; +}, "data">, unknown, TokenParams, unknown>; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| contract | [RequiredParam](./react.requiredparam.md)<Erc20> | an instance of a contract that extends the ERC20 spec (token, token drop, custom contract that follows the ERC20 spec) | + +Returns: + +import("@tanstack/react-query").UseMutationResult<Omit<{ receipt: import("@ethersproject/abstract-provider").TransactionReceipt; data: () => Promise<unknown>; }, "data">, unknown, [TokenParams](./react.tokenparams.md), unknown> + +a mutation object that can be used to mint a new NFT token to the connected wallet + +## Example + + +```jsx +const Component = () => { + const { + mutate: transferTokens, + isLoading, + error, + } = useTransferToken(">>YourERC20ContractInstance<<"); + + if (error) { + console.error("failed to transfer tokens", error); + } + + return ( + + ); +}; +``` + diff --git a/docs/snippets.json b/docs/snippets.json index f317900..d8da7ed 100644 --- a/docs/snippets.json +++ b/docs/snippets.json @@ -238,7 +238,7 @@ }, { "name": "useClaimToken", - "example": "const Component = () => {\n const {\n mutate: claimTokens,\n isLoading,\n error,\n } = useClaimToken(TokenDropContract);\n\n if (error) {\n console.error(\"failed to claim tokens\", error);\n }\n\n return (\n claimTokens({to: \"0x...\", amount: 100})}\n >\n Claim Tokens!\n \n );\n};", + "example": "const Component = () => {\n const {\n mutate: claimTokens,\n isLoading,\n error,\n } = useClaimToken(TokenDropContract);\n\n if (error) {\n console.error(\"failed to claim tokens\", error);\n }\n\n return (\n claimTokens({ to: \"0x...\", amount: 100 })}\n >\n Claim Tokens!\n \n );\n};", "reference": "https://portal.thirdweb.com/react/react.useclaimtoken" }, { @@ -423,7 +423,7 @@ }, { "name": "useClaimToken", - "example": "const Component = () => {\n const {\n mutate: claimTokens,\n isLoading,\n error,\n } = useClaimToken(TokenDropContract);\n\n if (error) {\n console.error(\"failed to claim tokens\", error);\n }\n\n return (\n claimTokens({to: \"0x...\", amount: 100})}\n >\n Claim Tokens!\n \n );\n};", + "example": "const Component = () => {\n const {\n mutate: claimTokens,\n isLoading,\n error,\n } = useClaimToken(TokenDropContract);\n\n if (error) {\n console.error(\"failed to claim tokens\", error);\n }\n\n return (\n claimTokens({ to: \"0x...\", amount: 100 })}\n >\n Claim Tokens!\n \n );\n};", "reference": "https://portal.thirdweb.com/react/react.useclaimtoken" }, { @@ -527,7 +527,7 @@ "subhooks": [ { "name": "useMintToken", - "example": "const Component = () => {\n const {\n mutate: mintNft,\n isLoading,\n error,\n } = useMintToken(\">>YourERC20ContractInstance<<\");\n\n if (error) {\n console.error(\"failed to mint nft\", error);\n }\n\n return (\n mintNft({ name: \"My awesome NFT!\" })}\n >\n Mint!\n \n );\n};", + "example": "const Component = () => {\n const {\n mutate: mintTokens,\n isLoading,\n error,\n } = useMintToken(\">>YourERC20ContractInstance<<\");\n\n if (error) {\n console.error(\"failed to mint tokens\", error);\n }\n\n return (\n mintTokens({ to: \"0x...\", amount: 1000 })}\n >\n Mint!\n \n );\n};", "reference": "https://portal.thirdweb.com/react/react.useminttoken" }, { diff --git a/etc/react.api.md b/etc/react.api.md index 712d766..7ec1b32 100644 --- a/etc/react.api.md +++ b/etc/react.api.md @@ -293,7 +293,7 @@ export interface ThirdwebSDKProviderProps extends Pick(contract: RequiredPara export function useMintToken(contract: RequiredParam): UseMutationResult Promise; -}, "data">, unknown, TokenMintParams, unknown>; +}, "data">, unknown, TokenParams, unknown>; // @public export function useMultiwrap(contractAddress?: string): Multiwrap | undefined; @@ -1571,6 +1571,15 @@ export type useTotalCirculatingSupplyParams = TContract extends Erc11 // @beta export function useTotalCount(contract: RequiredParam): UseQueryResult; +// @beta +export function useTransferBatchToken(contract: RequiredParam): UseMutationResult; + +// @beta +export function useTransferToken(contract: RequiredParam): UseMutationResult Promise; +}, "data">, unknown, TokenParams, unknown>; + // @beta export function useUnclaimedNFTs(contract: RequiredParam, queryParams?: QueryAllParams): UseQueryResult< { [x: string]: Json; diff --git a/src/hooks/async/token.ts b/src/hooks/async/token.ts index fac3f74..766d5c1 100644 --- a/src/hooks/async/token.ts +++ b/src/hooks/async/token.ts @@ -2,7 +2,7 @@ import { useActiveChainId } from "../../Provider"; import { ClaimTokenParams, RequiredParam, - TokenMintParams, + TokenParams, WalletAddress, } from "../../types"; import { @@ -19,7 +19,7 @@ import invariant from "tiny-invariant"; /** **********************/ /** - * Use this to get a the total supply of your Token contract. + * Use this to get a the total supply of your {@link Erc20} contract. * * @example * ```javascript @@ -45,7 +45,7 @@ export function useTokenSupply(contract: RequiredParam) { } /** - * Use this to get the balance of your Token contract for a given address. + * Use this to get the balance of your {@link Erc20} contract for a given address. * * @example * ```javascript @@ -79,25 +79,25 @@ export function useTokenBalance( /** **********************/ /** - * Use this to mint a new NFT on your ERC20 contract + * Use this to mint new tokens on your {@link Erc20} contract * * @example * ```jsx * const Component = () => { * const { - * mutate: mintNft, + * mutate: mintTokens, * isLoading, * error, * } = useMintToken(">>YourERC20ContractInstance<<"); * * if (error) { - * console.error("failed to mint nft", error); + * console.error("failed to mint tokens", error); * } * * return ( * @@ -115,7 +115,7 @@ export function useMintToken(contract: RequiredParam) { const queryClient = useQueryClient(); return useMutation( - (data: TokenMintParams) => { + (data: TokenParams) => { const { to, amount } = data; invariant(contract?.mint?.to, "contract does not support mint.to"); return contract.mint.to(to, amount); @@ -150,7 +150,7 @@ export function useMintToken(contract: RequiredParam) { * return ( * @@ -189,3 +189,116 @@ export function useClaimToken( }, ); } + +/** + * Use this to transfer tokens on your {@link Erc20} contract + * + * @example + * ```jsx + * const Component = () => { + * const { + * mutate: transferTokens, + * isLoading, + * error, + * } = useTransferToken(">>YourERC20ContractInstance<<"); + * + * if (error) { + * console.error("failed to transfer tokens", error); + * } + * + * return ( + * + * ); + * }; + * ``` + * + * @param contract - an instance of a contract that extends the ERC20 spec (token, token drop, custom contract that follows the ERC20 spec) + * @returns a mutation object that can be used to mint a new NFT token to the connected wallet + * @beta + */ +export function useTransferToken(contract: RequiredParam) { + const activeChainId = useActiveChainId(); + const contractAddress = contract?.getAddress(); + const queryClient = useQueryClient(); + + return useMutation( + (data: TokenParams) => { + const { to, amount } = data; + invariant(contract?.transfer, "contract does not support transfer"); + return contract.transfer(to, amount); + }, + { + onSettled: () => + invalidateContractAndBalances( + queryClient, + contractAddress, + activeChainId, + ), + }, + ); +} + +/** + * Use this to transfer batch tokens on your {@link Erc20} contract + * + * @example + * ```jsx + * const Component = () => { + * const { + * mutate: transferBatchTokens, + * isLoading, + * error, + * } = useTransferToken(">>YourERC20ContractInstance<<"); + * + * if (error) { + * console.error("failed to transfer batch tokens", error); + * } + * + * return ( + * + * ); + * }; + * ``` + * + * @param contract - an instance of a contract that extends the ERC20 spec (token, token drop, custom contract that follows the ERC20 spec) + * @returns a mutation object that can be used to mint a new NFT token to the connected wallet + * @beta + */ +export function useTransferBatchToken(contract: RequiredParam) { + const activeChainId = useActiveChainId(); + const contractAddress = contract?.getAddress(); + const queryClient = useQueryClient(); + + return useMutation( + (data: TokenParams[]) => { + invariant( + contract?.transferBatch, + "contract does not support transferBatch", + ); + const convertedData = data.map((token) => ({ + toAddress: token.to, + amount: token.amount, + })); + + return contract.transferBatch(convertedData); + }, + { + onSettled: () => + invalidateContractAndBalances( + queryClient, + contractAddress, + activeChainId, + ), + }, + ); +} diff --git a/src/types.ts b/src/types.ts index d7a2e37..79f3e44 100644 --- a/src/types.ts +++ b/src/types.ts @@ -34,11 +34,11 @@ export type WalletAddress = string; export type ContractAddress = string; /** - * The parameters to pass to the nft mint function. + * The parameters to pass to the mint and transfer functions. * * @beta */ -export type TokenMintParams = { +export type TokenParams = { to: WalletAddress; amount: string | number; };