From 807e5cf3e07d1564ac12f23dbe672e1bb13056cb Mon Sep 17 00:00:00 2001 From: Nacho Iacovino Date: Fri, 12 Aug 2022 02:54:45 +0200 Subject: [PATCH 1/6] Add burn hooks --- docs/react.burnnftparams.md | 23 ++++++++ docs/react.md | 4 ++ docs/react.tokenburnparams.md | 18 ++++++ docs/react.useburnnft.md | 86 +++++++++++++++++++++++++++ docs/react.useburntoken.md | 58 ++++++++++++++++++ docs/react.useminttoken.md | 2 +- docs/react.usetransferbatchtoken.md | 2 +- docs/react.usetransfertoken.md | 2 +- etc/react.api.md | 29 ++++++++- package.json | 2 +- src/hooks/async/nft.ts | 91 +++++++++++++++++++++++++++++ src/hooks/async/token.ts | 60 ++++++++++++++++++- src/types.ts | 19 ++++++ yarn.lock | 8 +-- 14 files changed, 391 insertions(+), 13 deletions(-) create mode 100644 docs/react.burnnftparams.md create mode 100644 docs/react.tokenburnparams.md create mode 100644 docs/react.useburnnft.md create mode 100644 docs/react.useburntoken.md diff --git a/docs/react.burnnftparams.md b/docs/react.burnnftparams.md new file mode 100644 index 0000000..2a851c8 --- /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: BigNumberish; +} : { + 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..d8f5797 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: BigNumberish; +} : { + 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..a75b1b7 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: BigNumberish } + : { 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" From e668dcc95bfbc8549d69f6f74bad94a9b4fc0ac2 Mon Sep 17 00:00:00 2001 From: Nacho Iacovino Date: Fri, 12 Aug 2022 02:55:16 +0200 Subject: [PATCH 2/6] v2.6.3-1 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 8d9efe5..7a91327 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@thirdweb-dev/react", - "version": "2.6.3-0", + "version": "2.6.3-1", "repository": { "type": "git", "url": "git+https://github.com:thirdweb-dev/react.git" From 07800505347d39afb9709a4efb66e3cfc57cec2d Mon Sep 17 00:00:00 2001 From: Nacho Iacovino <50103937+nachoiacovino@users.noreply.github.com> Date: Fri, 12 Aug 2022 19:04:38 +0200 Subject: [PATCH 3/6] Update src/types.ts Co-authored-by: Jonas Daniels --- src/types.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types.ts b/src/types.ts index a75b1b7..2f732ca 100644 --- a/src/types.ts +++ b/src/types.ts @@ -176,7 +176,7 @@ export type MintNFTReturnType = TContract extends Erc721 */ export type BurnNFTParams = TContract extends Erc1155 - ? { tokenId: BigNumberish; amount: BigNumberish } + ? { tokenId: BigNumberish; amount: Amount } : { tokenId: BigNumberish }; // DROPS // From 0f8d098dd957ea8dc93e4bd5205d861b7dc790cf Mon Sep 17 00:00:00 2001 From: Nacho Iacovino Date: Fri, 12 Aug 2022 19:08:41 +0200 Subject: [PATCH 4/6] v2.6.3-2 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 7a91327..dfb5481 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@thirdweb-dev/react", - "version": "2.6.3-1", + "version": "2.6.3-2", "repository": { "type": "git", "url": "git+https://github.com:thirdweb-dev/react.git" From 622954814ce9b1f0ef093605a6c3fdcfaaf58cde Mon Sep 17 00:00:00 2001 From: Nacho Iacovino Date: Fri, 12 Aug 2022 19:09:22 +0200 Subject: [PATCH 5/6] yarn build --- docs/react.burnnftparams.md | 2 +- etc/react.api.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/react.burnnftparams.md b/docs/react.burnnftparams.md index 2a851c8..204b9cf 100644 --- a/docs/react.burnnftparams.md +++ b/docs/react.burnnftparams.md @@ -14,7 +14,7 @@ The params for the [useBurnNFT()](./react.useburnnft.md) hook mutation. ```typescript export declare type BurnNFTParams = TContract extends Erc1155 ? { tokenId: BigNumberish; - amount: BigNumberish; + amount: Amount; } : { tokenId: BigNumberish; }; diff --git a/etc/react.api.md b/etc/react.api.md index d8f5797..ae6b274 100644 --- a/etc/react.api.md +++ b/etc/react.api.md @@ -91,7 +91,7 @@ export type AirdropNFTParams = { // @beta export type BurnNFTParams = TContract extends Erc1155 ? { tokenId: BigNumberish; - amount: BigNumberish; + amount: Amount; } : { tokenId: BigNumberish; }; From 4338973055253ff172c2375db6f36743deabe04e Mon Sep 17 00:00:00 2001 From: Nacho Iacovino Date: Fri, 12 Aug 2022 19:09:47 +0200 Subject: [PATCH 6/6] v2.6.3-3 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index dfb5481..f8dd5e9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@thirdweb-dev/react", - "version": "2.6.3-2", + "version": "2.6.3-3", "repository": { "type": "git", "url": "git+https://github.com:thirdweb-dev/react.git"