diff --git a/docs/tools/kit/index.md b/docs/tools/kit/index.md index f70eb57c89..8a386fe87b 100644 --- a/docs/tools/kit/index.md +++ b/docs/tools/kit/index.md @@ -24,6 +24,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 ## Installation @@ -421,6 +422,10 @@ function TransactionStatusComponent() { ### `useCrossVmTokenBalance` + +This feature is currently only supported on Testnet & Mainnet networks. Emulator support will be added in a future release. + + ```tsx import { useFlowQuery } from '@onflow/kit'; ``` @@ -580,5 +585,80 @@ function CrossVmBatchTransactionExample() { } ``` +--- + +### `useCrossVmSpendToken` + + +This feature is currently only supported on Testnet & Mainnet networks. Emulator support will be added in a future release. + + +```tsx +import { useCrossVmSpendToken } from "@onflow/kit" +``` + +Bridge FTs from Cadence to Flow EVM and execute arbitrary EVM transactions to atomically spend them. + +#### Parameters: +- `mutation?: UseMutationOptions` – Optional TanStackQuery mutation options + +Where `UseCrossVmSpendTokenMutateArgs` is defined as: + +```typescript +interface UseCrossVmSpendTokenMutateArgs { + vaultIdentifier: string; // Cadence vault identifier (e.g. "0x1cf0e2f2f715450.ExampleToken.Vault") + amount: string; // Amount of tokens to bridge, as a decimal string (e.g. "1.23") + calls: EVMBatchCall[]; // Array of EVM calls to execute after bridging +} +``` + +#### Returns: `UseCrossVmSpendTokenResult` + +Where `UseCrossVmSpendTokenResult` is defined as: + +```typescript +interface UseCrossVmSpendTokenResult extends Omit< + UseMutationResult, + "mutate" | "mutateAsync" +> { + spendToken: (args: UseCrossVmSpendTokenMutateArgs) => void; // Function to trigger the FT bridging and EVM calls + spendTokenAsync: (args: UseCrossVmSpendTokenMutateArgs) => Promise; // Async version of spendToken +} +``` + +```tsx +function CrossVmSpendTokenExample() { + const { spendToken, isPending, error, data: txId } = useCrossVmSpendToken() + + const handleSpendToken = () => { + spendToken({ + vaultIdentifier: "0x1cf0e2f2f715450.ExampleToken.Vault", // Cadence vault identifier + amount: "1.23", // Amount of tokens to bridge to EVM + calls: [ + { + abi: myEvmContractAbi, // EVM contract ABI + address: "0x01234567890abcdef01234567890abcdef", // EVM contract address + function: "transfer", // EVM function to call + args: [ + "0xabcdef01234567890abcdef01234567890abcdef", // Recipient address + ], + }, + ], + }) + } + + return ( +
+ + {isPending &&

Sending transaction...

} + {error &&

Error: {error.message}

} + {txId &&

Cadence Transaction ID: {txId}

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