diff --git a/docs/tools/kit/index.md b/docs/tools/kit/index.md index 8a386fe87b..3d4be465b4 100644 --- a/docs/tools/kit/index.md +++ b/docs/tools/kit/index.md @@ -25,6 +25,7 @@ sidebar_position: 1 - [`useCrossVmTokenBalance`](#usecrossvmtokenbalance) – Query fungible token balances across Cadence and Flow EVM - [`useCrossVmBatchTransaction`](#usecrossvmbatchtransaction) – Execute mutliple EVM transactions in a single atomic Cadence transaction - [`useCrossVmSpendToken`](#usecrossvmspendnft) – Bridge fungible tokens from Cadence to Flow EVM and execute arbitrary EVM transactions +- [`useCrossVmSpendNft`](#usecrossvmspendnft) – Bridge NFTs from Cadence to Flow EVM and execute arbitrary EVM transactions to atomically spend them ## Installation @@ -660,5 +661,80 @@ function CrossVmSpendTokenExample() { } ``` +--- + +### `useCrossVmSpendNft` + + +This feature is currently only supported on Testnet & Mainnet networks. Emulator support will be added in a future release. + + +```tsx +import { useCrossVmSpendNft } from "@onflow/kit" +``` + +Bridge NFTs from Cadence to Flow EVM and execute arbitrary EVM transactions to atomically spend them. + +#### Parameters: +- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options + +Where `UseCrossVmSpendFtMutateArgs` is defined as: + +```typescript +interface UseCrossVmSpendFtMutateArgs { + nftIdentifier: string // Cadence NFT identifier (e.g. "0x1cf0e2f2f715450.FlowNFT") + nftIds: string[] // Array of NFT IDs to bridge + calls: EVMBatchCall[] // Array of EVM calls to execute atomically +} +``` + +#### Returns: `UseCrossVmSpendNftResult` + +Where `UseCrossVmSpendNftResult` is defined as: + +```typescript +interface UseCrossVmSpendNftResult extends Omit< + UseMutationResult, + "mutate" | "mutateAsync" +> { + spendNft: (params: CrossVmSpendNftParams) => Promise + spendNftAsync: (params: CrossVmSpendNftParams) => Promise +} +``` + +```tsx +function CrossVmSpendNftExample() { + const { spendNft, isPending, error, data: txId } = useCrossVmSpendNft() + + const handleSpendNft = () => { + spendNft({ + nftIdentifier: "0x1cf0e2f2f715450.FlowNFT", // Cadence NFT identifier + nftIds: ["1"], // Array of NFT IDs to bridge + calls: [ + { + abi: contractAbi, // ABI of the EVM contract + contractAddress: "0x1234567890abcdef1234567890abcdef12345678", // EVM contract address + functionName: "transferNFT", + args: ["123"], // Example args + value: "1000000000000000000", // Amount in wei (if applicable) + gasLimit: "21000", // Gas limit for the EVM call + }, + ], + }) + } + + return ( +
+ + {isPending &&

Sending transaction...

} + {error &&

Error: {error.message}

} + {txId &&

Transaction ID: {txId}

} +
+ ) +} +``` + [commit-reveal scheme]: ../../build/advanced-concepts/randomness#commit-reveal-scheme [Configuration Guide]: ../flow-cli/flow.json/configuration.md