diff --git a/docs/tools/kit/index.md b/docs/tools/kit/index.md index 3f662c1bff..9624af0c2e 100644 --- a/docs/tools/kit/index.md +++ b/docs/tools/kit/index.md @@ -28,7 +28,8 @@ sidebar_position: 1 - [`useCrossVmBatchTransaction`](#usecrossvmbatchtransaction) – Execute mutliple EVM transactions in a single atomic Cadence transaction - [`useCrossVmTokenBalance`](#usecrossvmtokenbalance) – Query fungible token balances across Cadence and Flow EVM - [`useCrossVmSpendNft`](#usecrossvmspendnft) – Bridge NFTs from Cadence to Flow EVM and execute arbitrary EVM transactions to atomically spend them -- [`useCrossVmSpendToken`](#usecrossvmspendnft) – Bridge fungible tokens from Cadence to Flow EVM and execute arbitrary EVM transactions +- [`useCrossVmSpendToken`](#usecrossvmspendtoken) – Bridge fungible tokens from Cadence to Flow EVM and execute arbitrary EVM transactions +- [`useCrossVmTransactionStatus`](#usecrossvmtransactionstatus) – Track Cross-VM transaction status and EVM call results ## Installation @@ -853,5 +854,74 @@ function CrossVmSpendTokenExample() { } ``` +--- + +### `useCrossVmTransactionStatus` + + +This feature is currently only supported on Testnet & Mainnet networks. Emulator support will be added in a future release. + + +```tsx +import { useCrossVmTransactionStatus } from "@onflow/kit" +``` + +Subscribes to status updates for a given Cross-VM Flow transaction ID that executes EVM calls. This hook monitors the transaction status and extracts EVM call results if available. + +#### Parameters: + +- `id?: string` – Optional Flow transaction ID to monitor + +#### Returns: `UseCrossVmTransactionStatusResult` + +Where `UseCrossVmTransactionStatusResult` is defined as: + +```typescript +interface UseCrossVmTransactionStatusResult { + transactionStatus: TransactionStatus | null // Latest transaction status, or null before any update + evmResults?: CallOutcome[] // EVM transaction results, if available + error: Error | null // Any error encountered during status updates +} +``` + +Where `CallOutcome` is defined as: + +```typescript +interface CallOutcome { + status: "passed" | "failed" | "skipped" // Status of the EVM call + hash?: string // EVM transaction hash if available + errorMessage?: string // Error message if the call failed +} +``` + +```tsx +function CrossVmTransactionStatusComponent() { + const txId = "your-cross-vm-transaction-id-here" + const { transactionStatus, evmResults, error } = useCrossVmTransactionStatus({ id: txId }) + + if (error) return
Error: {error.message}
+ + return ( +
+
Flow Status: {transactionStatus?.statusString}
+ {evmResults && evmResults.length > 0 && ( +
+

EVM Call Results:

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