diff --git a/docs/react.burnnftparams.md b/docs/react.burnnftparams.md new file mode 100644 index 0000000..204b9cf --- /dev/null +++ b/docs/react.burnnftparams.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [BurnNFTParams](./react.burnnftparams.md) + +## BurnNFTParams 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 params for the [useBurnNFT()](./react.useburnnft.md) hook mutation. + +Signature: + +```typescript +export declare type BurnNFTParams = TContract extends Erc1155 ? { + tokenId: BigNumberish; + amount: Amount; +} : { + tokenId: BigNumberish; +}; +``` +References: [NFTContract](./react.nftcontract.md) + diff --git a/docs/react.md b/docs/react.md index f64f561..225ab23 100644 --- a/docs/react.md +++ b/docs/react.md @@ -21,6 +21,8 @@ import { useAddress } from "@thirdweb-dev/react" | [useAuctionWinner(contract, listingId)](./react.useauctionwinner.md) | (BETA) Use this to get the winner of an auction listing from your marketplace contract. | | [useBalance(tokenAddress)](./react.usebalance.md) | (BETA) A hook to get the native or (optional) ERC20 token balance of the connected wallet. | | [useBidBuffer(contract)](./react.usebidbuffer.md) | (BETA) Use this to get the buffer in basis points between offers from your marketplace contract. | +| [useBurnNFT(contract)](./react.useburnnft.md) | (BETA) Use this to burn an NFT on your [NFTContract](./react.nftcontract.md) | +| [useBurnToken(contract)](./react.useburntoken.md) | (BETA) Use this to burn tokens on your contract | | [useBuyNow(contract)](./react.usebuynow.md) | (BETA) Use this to buy out an auction listing from your marketplace contract. | | [useChainId()](./react.usechainid.md) |

Hook for accessing the chain ID of the network the current wallet is connected to

```javascript @@ -152,6 +154,7 @@ import { useWalletConnect } from "@thirdweb-dev/react" | Type Alias | Description | | --- | --- | | [AirdropNFTParams](./react.airdropnftparams.md) | (BETA) The params to pass to useTransferBatchNFT. | +| [BurnNFTParams](./react.burnnftparams.md) | (BETA) The params for the [useBurnNFT()](./react.useburnnft.md) hook mutation. | | [BuyNowParams](./react.buynowparams.md) | | | [ClaimIneligibilityParameters](./react.claimineligibilityparameters.md) | (BETA) The options to be passed as the second parameter to the useClaimIneligibilityReasons hook. | | [ClaimNFTParams](./react.claimnftparams.md) | (BETA) The params for the [useClaimNFT()](./react.useclaimnft.md) hook mutation. | @@ -165,6 +168,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. | +| [TokenBurnParams](./react.tokenburnparams.md) | (BETA) The parameters to pass to the burn function. | | [TokenParams](./react.tokenparams.md) | (BETA) The parameters to pass to the mint and transfer functions. | | [TransferNFTParams](./react.transfernftparams.md) | (BETA) The params to pass to useTransferNFT. | | [useNFTBalanceParams](./react.usenftbalanceparams.md) | (BETA) The params to pass to useNftBalance. | diff --git a/docs/react.tokenburnparams.md b/docs/react.tokenburnparams.md new file mode 100644 index 0000000..f7228c9 --- /dev/null +++ b/docs/react.tokenburnparams.md @@ -0,0 +1,18 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [TokenBurnParams](./react.tokenburnparams.md) + +## TokenBurnParams 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 burn function. + +Signature: + +```typescript +export declare type TokenBurnParams = { + amount: Amount; +}; +``` diff --git a/docs/react.useburnnft.md b/docs/react.useburnnft.md new file mode 100644 index 0000000..c625536 --- /dev/null +++ b/docs/react.useburnnft.md @@ -0,0 +1,86 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [useBurnNFT](./react.useburnnft.md) + +## useBurnNFT() 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 burn an NFT on your [NFTContract](./react.nftcontract.md) + +Signature: + +```typescript +export declare function useBurnNFT(contract: RequiredParam): import("@tanstack/react-query").UseMutationResult Promise; +}, "data">, unknown, BurnNFTParams, unknown>; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| contract | [RequiredParam](./react.requiredparam.md)<TContract> | an instance of a [NFTContract](./react.nftcontract.md) | + +Returns: + +import("@tanstack/react-query").UseMutationResult<Omit<{ receipt: import("@ethersproject/abstract-provider").TransactionReceipt; data: () => Promise<unknown>; }, "data">, unknown, [BurnNFTParams](./react.burnnftparams.md)<TContract>, unknown> + +a mutation object that can be used to burn an NFT token from the connected wallet + +## Example 1 + + +```jsx +const Component = () => { + const nftDrop = useNFTDrop(); + const { + mutate: burnNft, + isLoading, + error, + } = useBurnNFT(nftDrop); + + if (error) { + console.error("failed to burn nft", error); + } + + return ( + + ); +}; +``` + +## Example 2 + + +```jsx +const Component = () => { + const { contract } = useContract(); + const { + mutate: burnNft, + isLoading, + error, + } = useBurnNFT(contract?.nft); + + if (error) { + console.error("failed to burn nft", error); + } + + return ( + + ); +}; +``` + diff --git a/docs/react.useburntoken.md b/docs/react.useburntoken.md new file mode 100644 index 0000000..96beaa7 --- /dev/null +++ b/docs/react.useburntoken.md @@ -0,0 +1,58 @@ + + +[Home](./index.md) > [@thirdweb-dev/react](./react.md) > [useBurnToken](./react.useburntoken.md) + +## useBurnToken() 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 burn tokens on your contract + +Signature: + +```typescript +export declare function useBurnToken(contract: RequiredParam): import("@tanstack/react-query").UseMutationResult Promise; +}, "data">, unknown, TokenBurnParams, 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, [TokenBurnParams](./react.tokenburnparams.md), unknown> + +a mutation object that can be used to burn tokens from the connected wallet + +## Example + + +```jsx +const Component = () => { + const { + mutate: burnTokens, + isLoading, + error, + } = useBurnToken(">>YourERC20ContractInstance<<"); + + if (error) { + console.error("failed to burn tokens", error); + } + + return ( + + ); +}; +``` + diff --git a/docs/react.useminttoken.md b/docs/react.useminttoken.md index 08621c2..a277f46 100644 --- a/docs/react.useminttoken.md +++ b/docs/react.useminttoken.md @@ -28,7 +28,7 @@ export declare function useMintToken(contract: RequiredParam): import("@t 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 +a mutation object that can be used to mint new tokens to the connected wallet ## Example diff --git a/docs/react.usetransferbatchtoken.md b/docs/react.usetransferbatchtoken.md index 4f18995..d31f656 100644 --- a/docs/react.usetransferbatchtoken.md +++ b/docs/react.usetransferbatchtoken.md @@ -25,7 +25,7 @@ export declare function useTransferBatchToken(contract: RequiredParam): i 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 +a mutation object that can be used to transfer batch tokens ## Example diff --git a/docs/react.usetransfertoken.md b/docs/react.usetransfertoken.md index d875a28..51e2de5 100644 --- a/docs/react.usetransfertoken.md +++ b/docs/react.usetransfertoken.md @@ -28,7 +28,7 @@ export declare function useTransferToken(contract: RequiredParam): import 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 +a mutation object that can be used to transfer tokens ## Example diff --git a/etc/react.api.md b/etc/react.api.md index 7bba358..ae6b274 100644 --- a/etc/react.api.md +++ b/etc/react.api.md @@ -88,6 +88,14 @@ export type AirdropNFTParams = { addresses: AirdropInput; }; +// @beta +export type BurnNFTParams = TContract extends Erc1155 ? { + tokenId: BigNumberish; + amount: Amount; +} : { + tokenId: BigNumberish; +}; + // @public (undocumented) export type BuyNowParams = TListingType extends ListingType.Direct ? { id: BigNumberish; @@ -305,6 +313,11 @@ export interface ThirdwebSDKProviderWagmiWrapper extends Pick): UseQueryResu // @internal (undocumented) export function useBuiltinContract(contractType?: TContractType, contractAddress?: string): ContractForContractType | undefined; +// @beta +export function useBurnNFT(contract: RequiredParam): UseMutationResult Promise; +}, "data">, unknown, BurnNFTParams, unknown>; + +// @beta +export function useBurnToken(contract: RequiredParam): UseMutationResult Promise; +}, "data">, unknown, TokenBurnParams, unknown>; + // @beta export function useBuyNow(contract: RequiredParam): UseMutationResult { + * const nftDrop = useNFTDrop(); + * const { + * mutate: burnNft, + * isLoading, + * error, + * } = useBurnNFT(nftDrop); + * + * if (error) { + * console.error("failed to burn nft", error); + * } + * + * return ( + * + * ); + * }; + * ``` + * @example + * ```jsx + * const Component = () => { + * const { contract } = useContract(); + * const { + * mutate: burnNft, + * isLoading, + * error, + * } = useBurnNFT(contract?.nft); + * + * if (error) { + * console.error("failed to burn nft", error); + * } + * + * return ( + * + * ); + * }; + * ``` + * + * @param contract - an instance of a {@link NFTContract} + * @returns a mutation object that can be used to burn an NFT token from the connected wallet + * @beta + */ +export function useBurnNFT( + contract: RequiredParam, +) { + const activeChainId = useActiveChainId(); + const contractAddress = contract?.getAddress(); + const queryClient = useQueryClient(); + + return useMutation( + async (data: BurnNFTParams) => { + invariant(data.tokenId, "No tokenId provided"); + invariant(contract?.burn, "contract does not support burn"); + if (contract instanceof Erc1155) { + invariant("amount" in data, "amount not provided"); + const { tokenId, amount } = data; + return await contract.burn.tokens(tokenId, amount); + } + const { tokenId } = data; + return await contract.burn.token(tokenId); + }, + { + onSettled: () => + invalidateContractAndBalances( + queryClient, + contractAddress, + activeChainId, + ), + }, + ); +} diff --git a/src/hooks/async/token.ts b/src/hooks/async/token.ts index 766d5c1..8492577 100644 --- a/src/hooks/async/token.ts +++ b/src/hooks/async/token.ts @@ -2,6 +2,7 @@ import { useActiveChainId } from "../../Provider"; import { ClaimTokenParams, RequiredParam, + TokenBurnParams, TokenParams, WalletAddress, } from "../../types"; @@ -106,7 +107,7 @@ export function useTokenBalance( * ``` * * @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 + * @returns a mutation object that can be used to mint new tokens to the connected wallet * @beta */ export function useMintToken(contract: RequiredParam) { @@ -218,7 +219,7 @@ export function useClaimToken( * ``` * * @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 + * @returns a mutation object that can be used to transfer tokens * @beta */ export function useTransferToken(contract: RequiredParam) { @@ -271,7 +272,7 @@ export function useTransferToken(contract: RequiredParam) { * ``` * * @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 + * @returns a mutation object that can be used to transfer batch tokens * @beta */ export function useTransferBatchToken(contract: RequiredParam) { @@ -302,3 +303,56 @@ export function useTransferBatchToken(contract: RequiredParam) { }, ); } + +/** + * Use this to burn tokens on your {@link Erc20} contract + * + * @example + * ```jsx + * const Component = () => { + * const { + * mutate: burnTokens, + * isLoading, + * error, + * } = useBurnToken(">>YourERC20ContractInstance<<"); + * + * if (error) { + * console.error("failed to burn 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 burn tokens from the connected wallet + * @beta + */ +export function useBurnToken(contract: RequiredParam) { + const activeChainId = useActiveChainId(); + const contractAddress = contract?.getAddress(); + const queryClient = useQueryClient(); + + return useMutation( + (data: TokenBurnParams) => { + const { amount } = data; + invariant(contract?.burn, "contract does not support burn"); + return contract.burn.tokens(amount); + }, + { + onSettled: () => + invalidateContractAndBalances( + queryClient, + contractAddress, + activeChainId, + ), + }, + ); +} diff --git a/src/types.ts b/src/types.ts index c9c5b9e..2f732ca 100644 --- a/src/types.ts +++ b/src/types.ts @@ -44,6 +44,15 @@ export type TokenParams = { amount: Amount; }; +/** + * The parameters to pass to the burn function. + * + * @beta + */ +export type TokenBurnParams = { + amount: Amount; +}; + // NFTS // /** @@ -160,6 +169,16 @@ export type MintNFTReturnType = TContract extends Erc721 ? Awaited> : never; +/** + * The params for the {@link useBurnNFT} hook mutation. + * + * @beta + */ +export type BurnNFTParams = + TContract extends Erc1155 + ? { tokenId: BigNumberish; amount: Amount } + : { tokenId: BigNumberish }; + // DROPS // /** diff --git a/yarn.lock b/yarn.lock index 5dee9ee..f13f67f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1082,10 +1082,10 @@ resolved "https://registry.yarnpkg.com/@thirdweb-dev/contracts/-/contracts-3.0.3.tgz#ba83b7e28ab01a88358de479cf98cddbf835ff56" integrity sha512-TQRrML5SwbTb0VA1nu7VLxqIXrqMfvaXOBFT//yA9Jdd7GNsG4zSQHlHpkU4KWG1r766poG/AuXwz8KQ1A9IBg== -"@thirdweb-dev/sdk@^2.3.35-1": - version "2.3.35-1" - resolved "https://registry.yarnpkg.com/@thirdweb-dev/sdk/-/sdk-2.3.35-1.tgz#efd3eb869cde10999f05c252eeeedd5d4430fed1" - integrity sha512-A4uCbpZmj4sYXXA61GuG+M+aNyc/xb5fwX0tmFCUj47MENcmzfNM4oAew//lYp0EocIjVrrX6mchjL4tJP+nSA== +"@thirdweb-dev/sdk@^2.3.35": + version "2.3.35" + resolved "https://registry.yarnpkg.com/@thirdweb-dev/sdk/-/sdk-2.3.35.tgz#3a212aed78eec6e1ec2a00cdcb587ad075d8f165" + integrity sha512-jeoNjWe2AyPCmkMl6d7FJhk4Dpbb+T5OtItl8WCPkrqJh3/+Z3CfycLe0Pxm7urlfolgUL/O0LzPpQ2aVKiYFA== dependencies: "@thirdweb-dev/contracts" "^3.0.0" "@web-std/file" "^3.0.0"