This version of the kit deprecated the use of connex in favour of the SDK.

It may have some breaking changes based on how you integrated the kit inside your app. Please read more in details what changed from V1 and how to migrate to version 2 in the following section.

To add the package to your React app, you need to install the kit with all its peer dependencies as following:

If you have an app with some custom login (eg: login with email, login with google, etc.) and you want to use this kit and migrate your users you will need to:

• Create your Privy app

• Manually add your users or use Privy's APIs

Please refer to this documentation to import users through Privy APIs:

3) Toggle the "Pregenerate EVM Wallet" so an embedded wallet will be created and associated to the user.

4) If your users where logging in with social you may need to ask them to associate that social login method after they login first time with their email.

VeChain Kit supports 3 types of connections:

1) Privy

This connection type is often used by organizations like VeBetterDAO, Cleanify, and Greencart. When connected, users can back up their embedded wallets, sign transactions without confirmation prompts, and add login methods. By connecting with Privy, developers use their personal APP_ID and CLIENT_ID to create their own app on Privy.

2) Privy Cross App

When users integrate VeChain-kit using "Login with VeChain" and "Ecosystem" logins (eg: Mugshot and Greencart), this will be the default connection type. It is easily recognizable because login and wallet activities will open a secured popup window where the owner of the wallet will approve the actions.

3) Self-custody wallets

This connection type allows login with self custody wallets, and is using the dapp-kit package under the hood.

The available wallets are: VeWorld mobile, VeWorld extension, Sync2, and Wallet Connect for VeWorld mobile.

Component Overview

The hook offers a versatile suite of components for seamless integration into web applications. Below are some of the key components:

• WalletButton: Dynamically triggers either a login or account modal based on the user's connection status.

• ProfileCard: Displays essential details, including an avatar, description, and social links linked to a user's address.

• Transaction Visibility:

  • TransactionModal

  • TransactionToast

• AccountModal: Allows users to explore specific sections as needed.

• DAppKitWalletButton: Provides a focused interface for selecting wallet connection options.

These components collectively enhance user interaction and streamline.

Head over the to see all the components in action.

The kit provides hooks for developers to interact with smart contracts like VeBetterDAO, VePassport, veDelegate, and price oracles.

The hooks in this package provide a standardized way to interact with various blockchain and web services. All hooks are built using TanStack Query (formerly React Query), which provides powerful data-fetching and caching capabilities.

Common Features

Every hook in the @api directory returns a consistent interface that includes:

• data: The fetched data

• isLoading: Boolean indicating if the request is in progress

• isError: Boolean indicating if the request failed

• error: Error object if the request failed

• refetch: Function to manually trigger a new fetch

• isRefetching: Boolean indicating if a refetch is in progress

Additionally, these hooks integrate with TanStack Query's global features:

• Automatic background refetching

• Cache invalidation

• Optimistic updates

• Infinite queries (for pagination)

• Parallel queries

• Query retrying

• Query polling

Query Invalidation

All hooks use consistent query key patterns, making it easy to invalidate related queries. For example:

const queryClient = useQueryClient();
// Invalidate all blockchain queries
queryClient.invalidateQueries({ queryKey: ['VECHAIN_KIT'] });
// Invalidate specific query
queryClient.invalidateQueries({ queryKey: ['VECHAIN_KIT', 'CURRENT_BLOCK'] });

Caching Behavior

By default, most queries are configured with:

• staleTime: How long the data remains "fresh"

• cacheTime: How long inactive data remains in cache

• refetchInterval: For automatic background updates (if applicable)

These can be customized using TanStack Query's global configuration or per-hook options.

This guide covers all available authentication methods in VeChain Kit. Choose the approach that best fits your application's needs.

Overview

VeChain Kit provides four main authentication approaches:

1. Pre-built WalletButton Component - Fastest implementation with automatic state management

2. Custom Authentication UI - Full control over design and user experience

3. OAuth Social Login - Integrate with social providers (Privy self-hosted only)

4. Wallet-Only Connection - Direct wallet connection without social options

Method 1: Using the WalletButton Component

The simplest way to add authentication is using the pre-built WalletButton component. It automatically handles:

• Connection state management

• Login/logout button switching

• User profile display when connected

'use client';

import { WalletButton } from '@vechain/vechain-kit';

export function Page() {
    return (
        <WalletButton />
    );
}

For styling and customization options, see the WalletButton documentation.

Method 2: Building Custom Authentication UI

For complete control over the authentication experience, create a custom implementation using the provided hooks:

'use client';

import { useConnectModal, useAccountModal, useWallet } from '@vechain/vechain-kit';

export function CustomAuthButton() {
    const { connection } = useWallet();
    
    const { 
        open: openConnectModal, 
        close: closeConnectModal, 
        isOpen: isConnectModalOpen 
    } = useConnectModal();
    
    const { 
        open: openAccountModal, 
        close: closeAccountModal, 
        isOpen: isAccountModalOpen 
    } = useAccountModal();
    
    if (!connection.isConnected) {
        return (
            <button onClick={openConnectModal}>
                Connect Wallet
            </button>
        );
    }
    
    return (
        <button onClick={openAccountModal}>
            View Account
        </button>
    );
}

Method 3: OAuth Social Login (Self-Hosted Privy Only)

For applications using self-hosted Privy, you can implement OAuth authentication with popular social providers:

import { useLoginWithOAuth } from '@vechain/vechain-kit';

const SocialLoginComponent = () => {
    const { initOAuth } = useLoginWithOAuth();

    const handleOAuthLogin = async (provider: OAuthProvider) => {
        try {
            await initOAuth({ provider });
            console.log(`${provider} OAuth login initiated`);
        } catch (error) {
            console.error("OAuth login failed:", error);
        }
    };

    return (
        <div className="social-login-container">
            <h3>Sign in with:</h3>
            <div className="social-buttons">
                <button onClick={() => handleOAuthLogin('google')}>
                    <GoogleIcon /> Google
                </button>
                <button onClick={() => handleOAuthLogin('twitter')}>
                    <TwitterIcon /> Twitter
                </button>
                <button onClick={() => handleOAuthLogin('apple')}>
                    <AppleIcon /> Apple
                </button>
                <button onClick={() => handleOAuthLogin('discord')}>
                    <DiscordIcon /> Discord
                </button>
            </div>
        </div>
    );
};

export default SocialLoginComponent;

Supported OAuth Providers

• Google

• Twitter (X)

• Apple

• Discord

• GitHub

• LinkedIn

For detailed OAuth configuration, see the Login Hooks documentation.

Method 4: Wallet-Only Connection

To restrict authentication to wallet connections only (bypassing social login options):

import { useDAppKitWalletModal } from '@vechain/vechain-kit';

export const WalletOnlyLogin = () => {
    const { open: openWalletModal } = useDAppKitWalletModal();

    return (
        <button onClick={openWalletModal}>
            Connect Wallet
        </button>
    );
};

This method is useful when:

• Your app requires only crypto wallet authentication

• You want to bypass social login options

• You need a streamlined wallet-focused experience

Special Considerations

VeWorld Mobile Integration

When your application is accessed through the VeWorld mobile wallet browser, VeWorld is automatically enforced as the primary authentication method. This ensures seamless integration with the mobile wallet experience.

Authentication State Management

All authentication methods automatically sync with the VeChain Kit provider, ensuring consistent state across your application. You can access the current authentication state using:

import { useWallet } from '@vechain/vechain-kit';

function Component() {
    const { connection, address, source } = useWallet();
    
    if (connection.isConnected) {
        console.log('Connected wallet:', address);
        console.log('Connection source:', source);
    }
}

Error Handling

Always implement proper error handling for authentication flows:

const handleConnect = async () => {
    try {
        await openConnectModal();
    } catch (error) {
        console.error('Connection failed:', error);
        // Show user-friendly error message
    }
};

Next Steps

• Customize the WalletButton appearance

• Learn about authentication hooks

• Handle wallet interactions

• Implement transaction signing

This provides a high-level summary of all breaking changes in VeChain Kit v2. For detailed information on each topic, please refer to the specific guides linked below.

Major Breaking Changes

1. Connex Removal

• useConnex is completely removed and replaced with useThor

• This affects all blockchain interactions throughout your application

• See API Migration Guide →

2. New Contract Interaction Patterns

• Introduction of useCallClause for reading contract data

• New executeMultipleClausesCall for batch operations

• Complete rewrite of transaction patterns

• See API Migration Guide →

3. Updated Transaction Building

• New useBuildTransaction hook with improved type safety

• Better error handling and transaction status tracking

• See API Migration Guide →

4. Module Removal

• Entire VeBetterDAO module removed

• Several utility modules deprecated

• See Removed Features →

5. Hook Restructuring

• Many hooks moved to new locations for better organization

• Import paths have changed significantly

• See Hook Relocations →

Quick Decision Guide

Next Steps

1. Read the complete removal list to check if you use any removed features

2. Review the API migration patterns for code examples

3. Follow the migration checklist step by step

Getting Help

• GitHub Issues: Report issues

• Documentation: VeChain Kit v2 Docs

• Community: Discord

useCurrentBlock()

Fetches the current block from the blockchain with automatic updates.

const { data, isLoading, error } = useCurrentBlock();

Features:

• Auto-refreshes every 10 seconds

• Caches data for 1 minute

• Returns the latest block information as Connex.Thor.Block

Example:

function BlockInfo() {
  const { data: block } = useCurrentBlock();
  
  return <div>Current Block: {block?.number}</div>;
}

useTxReceipt()

Polls the blockchain for a transaction receipt until it is found or times out.

const { data, isLoading, error } = useTxReceipt(txId, blockTimeout);

Parameters:

• txId: (string) The transaction ID to monitor

• blockTimeout: (optional number) Number of blocks to wait before timing out (default: 5)

Returns:

• data: Transaction receipt (Connex.Thor.Transaction.Receipt)

• isLoading: Boolean indicating if the receipt is being fetched

• error: Error object if the operation fails

Example:

function TransactionStatus({ txId }) {
  const { data: receipt, isLoading } = useTxReceipt(txId);
  
  if (isLoading) return <div>Loading...</div>;
  return <div>Transaction Status: {receipt?.reverted ? 'Failed' : 'Success'}</div>;
}

Utility Functions

useEvents()

Fetches events from the blockchain based on specified criteria.

const events = await getEvents({
   abi,
   contractAddress,
   eventName,
   filterParams,
   mapResponse,
   nodeUrl,
});

1) Install and overwrite the Provider.

2) Replace all imports of @vechain/dapp-kit-react @vechain/dapp-kit and @vechain/dapp-kit-ui with @vechain/vechain-kit.

3) Wherever you use the account property from the useWallet() hook you need to access the user address differently:

// dapp-kit
const { account } = useWallet()
console.log(account) // 0x000000dsadsa

// vechain-kit
const { account } = useWallet()
console.log(account.address, account.domain, account.image)

4) Use the useSendTransaction() hook from @vechain/vechain-kit to send your transactions to the network. Read how to use the hook here.

6) If you use useConnex() by importing from dapp-kit, import it from vechain-kit.

7) If you are using certificate signing to authenticate your users with your backend to issue a jwt/session token you will need to switch to use signTypedData instead, since Privy and Smart Accounts does not support the VeChain certificate authentication signature type. Read how to do here.

8) Double-check your yarn.lock to see that all the @vechain/dapp-kit-react @vechain/dapp-kit and @vechain/dapp-kit-ui installs are using the the 1.5.0 version.

If you have your own Privy app, you can pass an additional prop with your settings.

import { VechainKitProvider } from '@vechain/vechain-kit';

export default function App({ Component, pageProps }: AppProps) {
    return (
        <VechainKitProvider
            privy={{
                appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID!,
                clientId: process.env.NEXT_PUBLIC_PRIVY_CLIENT_ID!,
                loginMethods: ['google', 'twitter', 'sms', 'email'],
                appearance: {
                    walletList: ['metamask', 'rainbow'],
                    accentColor: '#696FFD',
                    loginMessage: 'Select a social media profile',
                    logo: 'https://i.ibb.co/ZHGmq3y/image-21.png',
                },
                embeddedWallets: {
                    createOnLogin: 'all-users',
                },
                allowPasskeyLinking: true,
            }}
            ...
            //other props
        >
            {children}
        </VechainKitProvider>
    );
}

Go to privy.io and create an app. You will find the APP ID and the CLIENT ID in the App Settings tab.

For further information on how to implement Privy SDK please refer to their docs: https://docs.privy.io/

This project uses:

• @privy-io/react-auth for Privy connection type

• @privy-io/cross-app-connect for ecosystem cross app connection

You can import privy from the kit as

import { usePrivy } from "@vechain/vechain-kit";

const { user } = usePrivy();

Ensure that your project's peer dependencies align with VeChain Kit's specifications. Mismatched versions can cause installation failures, runtime errors, or unexpected behaviour.

Common Issues

• Package installation fails with peer dependency warnings

• Runtime errors about missing dependencies

• Version conflicts between VeChain Kit and your existing packages

Solution

1. Clean Installation

Often resolves dependency caching issues:

# Remove existing installations
rm -rf node_modules
rm package-lock.json # or yarn.lock

# Reinstall packages
npm install # or yarn install

1. Check Required Peer Dependencies

VeChain Kit requires specific versions of:

• Chakra UI React: ^2.8.2

• TanStack React Query: ^5.64.2

• VeChain DApp Kit React: 2.0.1

1. Update or Downgrade Packages

You may need to adjust package versions to maintain compatibility:

# Check what VeChain Kit expects
npm info @vechain/vechain-kit peerDependencies

# Install required peer dependencies
npm install @chakra-ui/react@^2.8.2 @tanstack/react-query@^5.64.2 @vechain/[email protected]

Quick Fixes

• Clean install: Delete node_modules and reinstall packages

• Check versions: Ensure compatible peer dependency versions

• Complete removal: Remove all old DApp Kit packages before installing VeChain Kit

Issues in This Section

Peer Dependencies

Resolving version conflicts and dependency mismatches when installing VeChain Kit.

From DApp Kit

Complete migration guide for projects upgrading from DApp Kit, including package removal and import updates.

Can't find your issue? Search our GitHub Issues or ask on Discord.

VeChain Kit includes built-in fee delegation handling. If you already have fee delegation in your app, you must remove it to avoid conflicts.

Problem

Using both your own fee delegation and VeChain Kit's delegation causes:

• Transaction failures

• Double delegation attempts

• Multiple signatures on transactions

• Incorrect transaction format

Solution

1. Remove Existing Fee Delegation

Remove all custom fee delegation logic from your application:

• Remove fee delegation middleware

• Remove delegation signing logic

• Remove any custom delegation providers

1. Configure VeChain Kit Fee Delegation

Simply provide the delegation URL in the VeChainKitProvider:

<VeChainKitProvider
  feeDelegation={{
    delegatorUrl: process.env.NEXT_PUBLIC_DELEGATOR_URL,
    delegateAllTransactions: false
  }}
  // ... other config
>
  <App />
</VeChainKitProvider>

1. Delegation Options

• delegatorUrl: Your fee delegation service URL

• delegateAllTransactions: Set to true to delegate fees for all transactions, including VeWorld users

Important Notes

• VeChain Kit handles all delegation logic internally

• No additional delegation setup required

• Works automatically with all supported wallets

Verification

To verify that delegation is working correctly:

1. Check that transactions only have one delegation signature

2. Monitor your delegation service logs

3. Ensure transactions complete successfully

Common Errors

"Transaction has multiple delegations": You still have custom delegation code active. Remove all custom delegation logic.

"Delegation failed": Check that your delegation URL is correct and the service is running.

VeChain Kit uses Chakra UI internally, which can cause styling conflicts with other CSS frameworks and custom styles.

Common Problems

• CSS framework styles being overridden by VeChain Kit

• VeChain Kit components not rendering correctly due to missing Chakra setup

• Theme conflicts when your app also uses Chakra UI

• Unexpected styling on images, buttons, or form elements

Quick Fixes

• Install Chakra UI as a peer dependency even if you don't use it directly

• Use CSS layers to control style precedence

• Wrap your app in ChakraProvider with ColorModeScript

Issues in This Section

Chakra Conflicts

Setting up Chakra UI properly and resolving conflicts when your app also uses Chakra.

CSS Framework Conflicts

Using CSS layers to resolve conflicts with Tailwind, Bootstrap, and other CSS frameworks.

Can't find your issue? Search our GitHub Issues or ask on Discord.

Runtime and functionality problems that occur when integrating VeChain Kit into your application.

Common Problems

• Fee delegation conflicts with existing setup

• Browser popup blocking for social login users

• Transaction failures due to configuration issues

• Signing delays causing security restrictions

Quick Fixes

• Remove existing fee delegation before using VeChain Kit's delegation

• Pre-fetch data before triggering transactions to avoid popup blocking

• Check configuration for proper delegation settings

Issues in This Section

Fee Delegation

Resolving conflicts when migrating from existing fee delegation setups and configuring VeChain Kit's delegation properly.

Privy Popup Blocking

Preventing browser popup blocking for social login users by properly structuring transaction flows.

Can't find your issue? Search our GitHub Issues or ask on Discord.

VeChain Kit is a comprehensive library designed to make building VeChain applications fast and straightforward. It offers:

• Seamless Wallet Integration: Support for VeWorld, Sync2, WalletConnect, VeChain Embedded Wallet, and social logins (powered by Privy).

• Unified Ecosystem Accounts: Leverage Privy’s Ecosystem feature to give users a single wallet across multiple dApps, providing a consistent identity within the VeChain network.

• Developer-Friendly Hooks: Easy-to-use React Hooks that let you read and write data on the VeChainThor blockchain.

• Pre-Built UI Components: Ready-to-use components (e.g., TransactionModal) to simplify wallet operations and enhance your users’ experience.

• Multi-Language Support: Built-in i18n for a global audience.

• Token Operations: Send tokens, check balances, manage VET domains, and more—all in one place.

Easier Integration We provide a standardized “kit” that quickly integrates social logins and VeChain Smart Accounts—without the hassle of manual contract deployment or configuration.

Resources

VeChain Kit Demo: https://vechain-kit.vechain.org/

Smart Account Factory: https://vechain.github.io/smart-accounts-factory/

NPM: https://www.npmjs.com/package/@vechain/vechain-kit

Check our Troubleshooting section.

Contact us on Discord: https://discord.com/invite/vechain

Open an issue on Github: https://github.com/vechain/vechain-kit/issues

Troubleshooting

Are you having issues using the kit? Join our discord server to receive support from our devs or open an issue on our Github!

Check our Troubleshooting section.

Contact us on Discord: https://discord.gg/wGkQnPpRVq

Open an issue on Github: https://github.com/vechain/vechain-kit/issues

useGetTokenUsdPrice

A React hook that fetches the current USD price for supported tokens (B3TR, VET, VTHO) from the VeChain oracle contract.

Usage

Parameters

Fetch the price for the following token symbols: 'B3TR', 'VET', 'VTHO'.

Returns

The hook returns a TanStack Query result object with the following properties:

Implementation Details

The hook internally:

• Uses the VeChain oracle contract to fetch real-time price data

• Automatically handles network configuration (mainnet/testnet)

• Caches results using TanStack Query

• Only fetches when both Thor connection and network type are available

Example with Multiple Tokens

Upgrading to unlocks multi-clause support, enhanced security, and other essential features for transactions on VeChain. This feature is available in VeChain Kit from .

When integrating social login in your app, users might have a version 1 smart account. This version doesn’t support multiclause transactions, potentially causing issues within your app.

To address this scenario, consider wrapping your onClick handler or using another suitable method to prompt users to upgrade their smart accounts to version 3.

The kit makes available both the hooks to know if the upgrade is required and the component for upgrading:

• useUpgradeRequired(smartAccountAddress, ownerAddress, targetVersion: 3) is the hook that will let you know if the user is on v1 and needs to upgrade to v3

• useUpgradeSmartAccountModal() is the hook that will allow you to open the upgrade modal, that the user will use to upgrade.

• You can also handle this with your own UI by using the useUpgradeSmartAccount(smartAccountAddress, targetVersion: 3) hook.

View other useful hooks .

Example usage

Example demo

With UI from the Kit

With custom UI

ProfileCard Component

The ProfileCard component provides a comprehensive display of user profile information, including avatar, domain, social links, and customization options.

Features

• Customizable header with generated background

• Avatar display with domain integration

• Social links integration (Email, Website, Twitter/X)

• Address display with copy functionality

• Edit and logout options for connected accounts

• Dark/Light mode support

Props

Usage example

Utility Hooks

The hooks provide utility functions for interacting with the VeChain network and tokens:

Network Utility Hooks

• useGetChainId: Retrieves the chain ID from the genesis block of the connected network

• useGetNodeUrl: Returns the node URL being used, either custom or default for the network

Token Utility Hooks

• useGetCustomTokenBalances: Fetches balances for multiple custom tokens for a given address, returning original, scaled, and formatted values

• useGetCustomTokenInfo: Retrieves token information (name, symbol, decimals) for a custom token address.

Legal Documents Hook

• useLegalDocuments: Retrieves the user's agreement status for required and optional legal documents, including terms of service, privacy policy, and cookie policy.

Usage Example

Are you having issues using the kit? Join our discord server to receive support from our devs or open an issue on our Github!

Check our .

Contact us on Discord:

Open an issue on Github:

Quick Links

If your issue is not addressed here, please reach out to us:

• Discord:

• GitHub Issues:

Common Issue Categories

Problems when upgrading from DApp Kit or managing dependencies

• Peer Dependencies

• From DApp Kit

CSS conflicts and theming problems

• Chakra UI Conflicts

• CSS Framework Conflicts

Runtime and functionality problems

• Fee Delegation

• Privy Popup Blocking

Before You Start

1. Check that you're using the latest version of VeChain Kit

2. Ensure all peer dependencies are correctly installed

3. Clear your build cache (rm -rf node_modules .next && npm install)

Can't find your issue? Search our or ask on .

If you're coming from DApp Kit or SDK, you may have version conflicts from different versions installed across your project.

Problem

Multiple versions of DApp Kit packages can cause:

• Version conflicts between different parts of your project

• Runtime errors from competing implementations

• Unexpected behaviour from mixed package versions

Solution

1. Completely Remove DApp Kit Packages

Remove all existing DApp Kit packages from your project:

1. Completely Remove DApp Kit Packages

VeChain Kit provides similar functionality with updated component names:

1. Clean Installation

After removing old packages:

Component Mapping

Verification

Ensure clean migration:

• No dapp-kit packages in package.json

• All imports updated to use @vechain/vechain-kit

• Component names updated to VeChain Kit equivalents

VeChain Kit components are wrapped in their own Chakra Provider (v2), ensuring consistent styling throughout the modals. This can cause conflicts if your app also uses Chakra UI.

Problem

• VeChain Kit components not rendering correctly

• Theme conflicts when your app uses Chakra UI

• Missing styles or unexpected appearance

Solution

Install Chakra UI

Even if you don't use Chakra in your app, it's required as a peer dependency:

Setup ChakraProvider

Wrap your app with ChakraProvider and include ColorModeScript:

Key Requirements

The essential setup:

Framework Flexibility

You can keep using whatever frontend framework you prefer. The important part is defining the ChakraProvider wrapper for VeChain Kit components to function properly.

Common Issue

One common issue is missing the <ColorModeScript /> component, which can cause styling inconsistencies. Always include it within your ChakraProvider.

VetDomains Hooks

The hooks provide tools for interacting with VET domains and their functionality:

Domain Resolution Hooks

• useVechainDomain: Resolves VET domains to addresses and vice versa, returning domain info and validation status

• useIsDomainProtected: Checks if a domain is protected from claiming

• useGetDomainsOfAddress: Gets all domains owned by an address, with optional parent domain filtering

Domain Record Management Hooks

• useGetTextRecords: Gets all text records for a domain

• useGetAvatar: Gets the avatar URL for a domain. This hook will return directly the URL of the image, removing the need for developers to convert the URI to URL manually. The response can be null if the domain name does not exist or if there is no avatar attached to this domain.

• useGetAvatarOfAddress : This hook will check if the address has any primary domain name set, if yes it will fetch and return the avatar URL (again, no need to manually convert URI to URL, the hook does it). If there is no domain name attached to it or if there is no avatar attached to the domain, it will return the Picasso image.

• useGetResolverAddress: Gets the resolver contract address for a domain

• useUpdateTextRecord: Updates text records for a domain with transaction handling

Subdomain Management Hooks

• useClaimVeWorldSubdomain: Claims a VeWorld subdomain with transaction handling and success/error callbacks

Usage Example

/**
 * Domain Management Hooks
 * The hooks provide tools for interacting with VET domains and their functionality
 */

// Domain Resolution Hooks
- `useVechainDomain(addressOrDomain: string)`: 
  Returns { address?: string; domain?: string; isValidAddressOrDomain: boolean }
  // Resolves VET domains to addresses and vice versa

- `useIsDomainProtected(domain: string)`: 
  Returns boolean
  // Checks if a domain is protected from claiming

- `useGetDomainsOfAddress(address: string, parentDomain?: string)`: 
  Returns { domains: Array<{ name: string }> }
  // Gets all domains owned by an address

// Domain Record Management Hooks
- `useGetTextRecords(domain: string)`: 
  Returns TextRecords object
  // Gets all text records for a domain

- `useGetAvatar(domain: string)`: 
  Returns string | null
  // Gets the avatar URL for a domain

- `useGetResolverAddress(domain: string)`: 
  Returns string
  // Gets the resolver contract address for a domain

- `useUpdateTextRecord({
    onSuccess?: () => void,
    onError?: (error: Error) => void,
    signerAccountAddress?: string,
    resolverAddress: string
  })`: 
  Returns { sendTransaction, isTransactionPending, error }
  // Updates text records for a domain

// Subdomain Management Hooks
- `useClaimVeWorldSubdomain({
    subdomain: string,
    domain: string,
    onSuccess?: () => void,
    onError?: (error: Error) => void,
    alreadyOwned?: boolean
  })`: 
  Returns { sendTransaction, isTransactionPending, error }
  // Claims a VeWorld subdomain

// Example Usage
const ExampleComponent = () => {
    const address = "0x...";
    const domain = "example.vet";
    
    // Resolve domain or address
    const { data: domainInfo } = useVechainDomain(address);
    
    // Check domain protection
    const { data: isProtected } = useIsDomainProtected(domain);
    
    // Get owned domains
    const { data: ownedDomains } = useGetDomainsOfAddress(address);
    
    // Get domain records
    const { data: textRecords } = useGetTextRecords(domain);
    const { data: avatar } = useGetAvatar(domain);
    const { data: avatarOfAddress } = useGetAvatarOfAddress(address);
    
    // Update domain records
    const { sendTransaction: updateRecord } = useUpdateTextRecord({
        onSuccess: () => console.log("Record updated"),
        resolverAddress: "0x..."
    });
    
    // Claim subdomain
    const { sendTransaction: claimSubdomain } = useClaimVeWorldSubdomain({
        subdomain: "mysub",
        domain: "veworld.vet",
        onSuccess: () => console.log("Subdomain claimed")
    });

    console.log(
        'Domain Info:', domainInfo,
        'Is Protected:', isProtected,
        'Owned Domains:', ownedDomains,
        'Text Records:', textRecords,
        'Avatar:', avatar
    );

    return (
        // Your component JSX
    );
};

/*
Requirements:
- All hooks require a valid thor connection
- Appropriate network configuration must be set
- Valid input parameters must be provided
- Most hooks are part of the @tanstack/react-query ecosystem

Additional Notes:
- Domain resolution works for both .vet domains and addresses
- Text records can include various fields like email, description, url, etc.
- Subdomain claiming is specific to veworld.vet domains
- Protection status affects whether a domain can be claimed or transferred
*/

Browser popup blocking can affect users using social login (Privy) when operations delay the signing popup.

Problem

When using Privy for social login (cross-app connection), browsers may block the confirmation popup if there's a delay between user action and popup trigger.

What Causes This

• Fetching data after button click

• API calls before signing

• Any async operations between click and popup

Solution

Pre-fetch Data Before Transaction

Ensure all required data is loaded before the user clicks the button:

// ✅ Good: Pre-fetch data
const { data } = useQuery(['someData'], fetchSomeData);
const sendTx = () => sendTransaction(data);

// ❌ Bad: Fetching data during the transaction
const sendTx = async () => {
  const data = await fetchSomeData();  // This delay causes popup blocking
  return sendTransaction(data);
};

Best Practices

1. Load Data Early

// Load data when component mounts or when form changes
const { data: gasPrice } = useQuery(['gasPrice'], fetchGasPrice, {
    staleTime: 30000 // Cache for 30 seconds
});
// Transaction handler is instant
const handleTransaction = () => {
    sendTransaction({
        gasPrice,
        // ... other pre-loaded data
    });
};

1. Show Loading States

const MyComponent = () => {
    const { data, isLoading } = useQuery(['requiredData'], fetchData);

    return (
      <button 
        onClick={() => sendTransaction(data)}
        disabled={isLoading}
      >
        {isLoading ? 'Preparing...' : 'Send Transaction'}
      </button>
    );
  };

1. Avoid Async in Click Handlers

// ❌ Avoid
onClick={async () => {
  const result = await someAsyncOperation();
  sendTransaction(result);
}}

// ✅ Better
onClick={() => {
  sendTransaction(preLoadedData);
}}

Testing

To test if your implementation avoids popup blocking:

1. Use social login (Privy)

2. Click transaction buttons

3. Popup should appear immediately

4. No browser blocking warnings

Common Scenarios

• Form submissions: Validate and prepare data before submit button is enabled

• Token approvals: Pre-fetch allowance amounts

• Multi-step transactions: Load all data for subsequent steps upfront

With every name come a set of records. These records are key value pairs that can be used to store information about the profile. Think of this as a user's digital backpack. Utalized for storage of preferences, public details, and more.

Types of Records

Here are some of the most commonly used records:

Other Records

Currently there are a few records that have been standardised. However you are welcome to store any key value pair you desire. We generally recommend to stick to a pattern, or prefix things with your app or protocol (eg. com.discord, or org.reddit), as such to avoid collisions.

Header/Banner Record

One of the newer standardised records is the "header" record. This header record, similar to the avatar record, accepts any IPFS, Arweave, EIP155, or regular URL to an image resource. The image is then displayed as a banner on the profile page and tends to be in a 1:3 aspect ratio.

Setting Records

When records are loaded they are loaded from the resolver responsible for the name. As resolvers are user controlled, we cannot guarantee a write function is available. This makes it a more in-depth process to update a users records.

Keep reading how to integrate with the VeChain Kit

Use our pre built TransactionModal or TransactionToast components to show your users the progress and outcome of the transaction, or build your own UX and UI.

Usage example

'use client';

import {
    useWallet,
    useSendTransaction,
    useTransactionModal,
    TransactionModal,
    getConfig
} from '@vechain/vechain-kit';
import { IB3TR__factory } from '@vechain/vechain-kit/contracts';
import { humanAddress } from '@vechain/vechain-kit/utils';
import { useMemo, useCallback } from 'react';

export function TransactionExamples() {
    const { account } = useWallet();
    const b3trMainnetAddress = getConfig("main").b3trContractAddress;
    
    const clauses = useMemo(() => {
        const B3TRInterface = IB3TR__factory.createInterface();

        const clausesArray: any[] = [];
        clausesArray.push({
            to: b3trMainnetAddress,
            value: '0x0',
            data: B3TRInterface.encodeFunctionData('transfer', [
                "0x0, // receiver address
                '0', // 0 B3TR (in wei)
            ]),
            comment: `This is a dummy transaction to test the transaction modal. Confirm to transfer ${0} B3TR to ${humanAddress("Ox0")}`,
            abi: B3TRInterface.getFunction('transfer'),
        });

        return clausesArray;
    }, [connectedWallet?.address]);

    const {
        sendTransaction,
        status,
        txReceipt,
        resetStatus,
        isTransactionPending,
        error,
    } = useSendTransaction({
        signerAccountAddress: account?.address ?? '',
    });

    const {
        open: openTransactionModal,
        close: closeTransactionModal,
        isOpen: isTransactionModalOpen,
    } = useTransactionModal();

    // This is the function triggering the transaction and opening the modal
    const handleTransaction = useCallback(async () => {
        openTransactionModal();
        await sendTransaction(clauses);
    }, [sendTransaction, clauses, openTransactionModal]);
    
    const handleTryAgain = useCallback(async () => {
        resetStatus();
        await sendTransaction(clauses);
    }, [sendTransaction, clauses, resetStatus]);

    return (
        <>
            <button
                onClick={handleTransactionWithModal}
                isLoading={isTransactionPending}
                isDisabled={isTransactionPending}
            >
                Send B3TR
            </button>

            <TransactionModal
                isOpen={isTransactionModalOpen}
                onClose={closeTransactionModal}
                status={status}
                txReceipt={txReceipt}
                txError={error}
                onTryAgain={handleTryAgain}
                uiConfig={{
                    title: 'Test Transaction',
                    description: `This is a dummy transaction to test the transaction modal. Confirm to transfer ${0} B3TR to ${
                        account?.address
                    }`,
                    showShareOnSocials: true,
                    showExplorerButton: true,
                    isClosable: true,
                }}
            />
        </>
    );
}

To prompt users to review and accept your policies, like Terms and Conditions, Privacy Policy, or Cookie Policy, VeChainKit offers a simple plug-and-play solution.

You can avoid building your own if you haven't already.

By enabling also the tracking consent, you will allow VeChainKit to prompt your users to collect data to improve the kit.

When the legalDocuments option is configured, the users will see:

• Left: A modal prompt when connecting their wallet, requiring them to review and accept required and optional legal documents.

• Right: A summary view under Settings > General > Terms and Policies, showing which policies they’ve accepted and when.

import { VechainKitProvider } from '@vechain/vechain-kit';

export default function App({ Component, pageProps }: AppProps) {
    return (
        <VechainKitProvider
            legalDocuments={{
                allowAnalytics: true, // Enables optional consent for VeChainKit tracking

                cookiePolicy: [
                    {
                        displayName: 'MyApp Policy', // (Optional) Custom display label
                        url: 'https://www.myapp.com/cookie-policy',
                        version: 1, // Increment to re-prompt users
                        required: false, // Optional: User sees a checkbox to opt in
                    },
                ],

                privacyPolicy: [
                    {
                        url: 'https://www.myapp.com/privacy-policy',
                        version: 1, // Increment to re-prompt users
                        required: false, // Optional: can be skipped or rejected
                    },
                ],

                termsAndConditions: [
                    {
                        displayName: 'MyApp T&C',
                        url: 'https://www.myapp.com/terms-and-conditions',
                        version: 1, // Increment to re-prompt users
                        required: true, // Required: must be accepted to proceed
                    },
                ],
            }}
            // ... other props
        >
            {children}
        </VechainKitProvider>
    );
}

Key Options

Use our pre built TransactionModal or TransactionToast components to show your users the progress and outcome of the transaction, or build your own UX and UI.

Usage example

'use client';
import { useWallet, useSendTransaction, useTransactionModal, TransactionModal, getConfig } from '@vechain/vechain-kit'; 
import { IB3TR__factory } from '@vechain/vechain-kit/contracts'; 
import { humanAddress } from '@vechain/vechain-kit/utils'; 
import { useMemo, useCallback } from 'react';

export function TransactionExamples() { const { account } = useWallet(); 
    const b3trMainnetAddress = getConfig("main").b3trContractAddress;

    const clauses = useMemo(() => {
        const B3TRInterface = IB3TR__factory.createInterface();
    
        const clausesArray: any[] = [];
        clausesArray.push({
            to: b3trMainnetAddress,
            value: '0x0',
            data: B3TRInterface.encodeFunctionData('transfer', [
                "0x0, // receiver address
                '0', // 0 B3TR (in wei)
            ]),
            comment: `This is a dummy transaction to test the transaction modal. Confirm to transfer ${0} B3TR to ${humanAddress("Ox0")}`,
            abi: B3TRInterface.getFunction('transfer'),
        });
    
        return clausesArray;
    }, [connectedWallet?.address]);

    const {
        sendTransaction,
        status,
        txReceipt,
        resetStatus,
        isTransactionPending,
        error,
    } = useSendTransaction({
        signerAccountAddress: account?.address ?? '',
    });

    const {
        open,
        close,
        isOpen
    } = useTransactionToast();

    // This is the function triggering the transaction and opening the toast
    const handleTransaction = useCallback(async () => {
        open();
        await sendTransaction(clauses);
    }, [sendTransaction, clauses, open]);

    const handleTryAgain = useCallback(async () => {
        resetStatus();
        await sendTransaction(clauses);
    }, [sendTransaction, clauses, resetStatus]);

    return (
        <>
            <button
                onClick={handleTransactionWithModal}
                isLoading={isTransactionPending}
                isDisabled={isTransactionPending}
            >
                Send B3TR
            </button>
    
            <TransactionToast
                isOpen={isOpen}
                onClose={close}
                status={status}
                txReceipt={txReceipt}
                txError={error}
                onTryAgain={handleTryAgain}
                title: 'Test Transaction',
                description: `This is a dummy transaction to test the transaction modal. Confirm to transfer ${0} B3TR to ${
                    account?.address
                }`
            />
        </>
    );
}

TypeScript Compilation Errors

Type Mismatch Errors

BigInt Serialization Errors

React Query Issues

Cache Invalidation Not Working

Contract Interaction Issues

Migration from manual ABI lookup:

Transaction Building Fails

Performance Issues

Too Many Network Requests

Network Issues

RPC Endpoint Problems

Testing Issues

Mocking Problems

Login Hooks

The hooks provide authentication methods for VeChain applications:

Authentication Hooks

• useLoginWithPasskey: Hook for authenticating using passkeys (biometric/device-based authentication)

• useLoginWithOAuth: Hook for authenticating using OAuth providers (Google, Twitter, Apple, Discord)

• useLoginWithVeChain: Hook for authenticating using VeChain wallet

Types

Usage example

NFT Hooks

The hooks provide tools for interacting with NFTs (Non-Fungible Tokens) on VeChain:

NFT Data Hooks

• useNFTImage: Fetches NFT image and metadata from IPFS, handling the complete flow from token ID to final image

• useNFTMetadataUri: Retrieves the metadata URI for an NFT using its token ID

Types

Example usage

This guide covers how to set up and configure the VeChainKitProvider in your application.

Basic Setup

To use VeChain Kit in your application, wrap your app with the VeChainKitProvider:

'use client';

import { VeChainKitProvider } from "@vechain/vechain-kit";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <VeChainKitProvider
      network={{ type: "test" }}
      feeDelegation={{
        delegatorUrl: "https://sponsor-testnet.vechain.energy/by/441",
        delegateAllTransactions: false,
      }}
    >
      {children}
    </VeChainKitProvider>
  );
}

Next.js Configuration

For Next.js applications, dynamically import the provider to avoid SSR issues:

import dynamic from 'next/dynamic';

const VeChainKitProvider = dynamic(
  async () => (await import('@vechain/vechain-kit')).VeChainKitProvider,
  { ssr: false }
);

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <VeChainKitProvider
      // ... configuration
    >
      {children}
    </VeChainKitProvider>
  );
}

Complete Configuration Example

Here's a comprehensive example with all available options:

'use client';

import { VeChainKitProvider } from "@vechain/vechain-kit";

export function VeChainKitProviderWrapper({ children }: { children: React.ReactNode }) {
  return (
    <VeChainKitProvider
      // Network Configuration
      network={{
        type: "test", // "main" | "test" | "solo"
      }}
      
      // Fee Delegation
      feeDelegation={{
        delegatorUrl: "https://sponsor-testnet.vechain.energy/by/441",
        delegateAllTransactions: false, // Set to true to delegate all transactions
      }}
      
      // Login Methods Configuration
      loginMethods={[
        { method: "vechain", gridColumn: 4 },
        { method: "dappkit", gridColumn: 4 },
        { method: "ecosystem", gridColumn: 4 },
      ]}
      
      // DApp Kit Configuration
      dappKit={{
        allowedWallets: ["veworld", "wallet-connect", "sync2"],
        walletConnectOptions: {
          projectId: process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
          metadata: {
            name: "Your DApp Name",
            description: "Your DApp description visible in wallets",
            url: typeof window !== "undefined" ? window.location.origin : "",
            icons: ["https://your-domain.com/logo.png"],
          },
        },
      }}
      
      // UI Configuration
      darkMode={false}
      language="en"
      allowCustomTokens={false}
      
      // Login Modal UI Customization
      loginModalUI={{
        logo: '/your-logo.png',
        description: 'Welcome to our DApp',
      }}
    >
      {children}
    </VeChainKitProvider>
  );
}

Configuration Options

Network Configuration

network: {
  type: "main" | "test" | "solo" // Select mainnet or testnet or solo
}

Fee Delegation

Configure transaction fee sponsorship:

feeDelegation: {
  delegatorUrl: string,           // Fee delegation service URL
  delegateAllTransactions: boolean // true: delegate all | false: only social login
}

Note: Social login transaction sponsorship is mandatory and always enabled.

Login Methods

Configure available authentication methods with a flexible grid layout:

loginMethods: [
  // Always available methods
  { method: "vechain", gridColumn: 4 },    // VeChain login
  { method: "dappkit", gridColumn: 4 },    // VeChain wallets
  { method: "ecosystem", gridColumn: 4 },  // Ecosystem apps (Mugshot, Cleanify, Greencart, etc.)
  
  // Privy-dependent methods (require privy configuration)
  { method: "email", gridColumn: 2 },      // Email login
  { method: "passkey", gridColumn: 2 },    // Passkey authentication
  { method: "google", gridColumn: 4 },     // Google OAuth
  { method: "more", gridColumn: 2 },       // Additional Privy methods
]

Grid Layout: The gridColumn property determines the width of each login option in the modal (based on a 4-column grid).

DApp Kit Configuration

Configure wallet connection options:

dappKit: {
  allowedWallets: ["veworld", "wallet-connect", "sync2"],
  walletConnectOptions: {
    projectId: "YOUR_WALLET_CONNECT_PROJECT_ID", // Get from https://cloud.reown.com
    metadata: {
      name: string,
      description: string,
      url: string,
      icons: string[]
    }
  }
}

Privy Integration (Optional)

To enable social login methods, configure Privy:

<VeChainKitProvider
  privy={{
    appId: "your-privy-app-id",
    clientId: "your-privy-client-id",
    // Additional Privy configuration
  }}
  loginMethods={[
    // Now you can use Privy-dependent methods
    { method: "email", gridColumn: 2 },
    { method: "google", gridColumn: 4 },
    { method: "passkey", gridColumn: 2 },
  ]}
>
  {children}
</VeChainKitProvider>

Type Safety with Privy

TypeScript enforces that Privy-dependent methods can only be used when Privy is configured:

// ❌ This will show a type error
const invalidConfig = {
  // No privy configuration
  loginMethods: [
    { method: 'email' }  // Type error: 'email' requires Privy
  ]
};

// ✅ This is valid
const validConfig = {
  privy: { appId: 'xxx', clientId: 'yyy' },
  loginMethods: [
    { method: 'email' },   // OK: Privy is configured
    { method: 'vechain' }  // OK: Always available
  ]
};

Ecosystem Apps Configuration

Customize which ecosystem apps appear in the login modal:

<VeChainKitProvider
  loginMethods={[
    { method: "ecosystem", gridColumn: 4 }
  ]}
  ecosystemApps={{
    allowedApps: ["app-id-1", "app-id-2"], // Find app IDs in Privy dashboard
  }}
>
  {children}
</VeChainKitProvider>

Environment Variables

Required environment variables:

# .env.local
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=your_project_id_here

Best Practices

1. Dynamic Import: Always use dynamic import in Next.js to avoid SSR issues

2. Environment Variables: Store sensitive configuration in environment variables

3. Fee Delegation: Consider your fee delegation strategy based on user experience needs

4. Login Methods: Choose login methods that match your target audience

5. Metadata: Provide clear app metadata for wallet connection requests

Next Steps

• Implement Authentication Methods

• Configure Fee Delegation

• Customize UI Theme

• Handle Wallet Interactions

What's Changed in 2.0

Major Breaking Changes

• Connex Removal: useConnex is replaced with useThor

• New Contract Interaction Patterns: Introduction of useCallClause and executeMultipleClausesCall

• Enhanced Transaction Building: New useBuildTransaction hook with improved type safety

• Improved Type Safety: Better TypeScript support with stricter typing

• useEvents() hook was refactored, more here

• The following hooks were also removed in order to improve permeances.

Migration Path

Preparation Steps

1. Create a git branch for migration

2. Identify all places where useConnex is used (This is the main breaking change and easiest to find)

3. Run tsc compiler to see all broken references

4. Fix the compiler errors and migrate incrementally. The new methods provide type-safe returns that will guide you

5. Verify functionality as you fix each error

6. Ensure you have adequate test coverage before starting

Getting Help

• Documentation: Refer to individual migration guide sections

• GitHub Issues: Report issues

Next Steps

1. Start with the API Changes guide to update your core dependencies and imports

2. Review Contract Patterns to understand new interaction methods

3. Apply Best Practices for optimal performance

4. Consult Troubleshooting if you encounter issues

IPFS Hooks

The hooks provide tools for interacting with IPFS (InterPlanetary File System):

Image Hooks

• useIpfsImage: Fetches NFT media from IPFS, supporting various image formats (JPEG, PNG, GIF, etc.)

• useIpfsImageList: Fetches multiple IPFS images in parallel

• useSingleImageUpload: Handles single image upload with optional compression

• useUploadImages: Manages multiple image uploads with compression support

Metadata Hooks

• useIpfsMetadata: Fetches and optionally parses JSON metadata from IPFS

• useIpfsMetadatas: Fetches multiple IPFS metadata files in parallel

Usage Example

// Example usage of IPFS hooks
import { 
    useIpfsImage, 
    useIpfsMetadata,
    useSingleImageUpload,
    useUploadImages
} from '@vechain/vechain-kit';

const ExampleComponent = () => {
    // Fetch an NFT image from IPFS
    const { 
        data: imageData,
        isLoading: isImageLoading,
        error: imageError 
    } = useIpfsImage("ipfs://...");

    // Fetch metadata from IPFS
    const { 
        data: metadata,
        isLoading: isMetadataLoading,
        error: metadataError 
    } = useIpfsMetadata<{ 
        name: string; 
        description: string 
    }>("ipfs://...", true); // parse as JSON

    // Handle single image upload
    const {
        uploadedImage,
        onUpload: handleSingleUpload,
        onRemove: handleSingleRemove,
        isUploading: isSingleUploading
    } = useSingleImageUpload({
        compressImage: true,
        defaultImage: undefined,
        maxSizeMB: 0.4,
        maxWidthOrHeight: 1920
    });

    // Handle multiple image uploads
    const {
        uploadedImages,
        onUpload: handleMultipleUpload,
        onRemove: handleMultipleRemove,
        isUploading: isMultipleUploading
    } = useUploadImages({
        compressImages: true,
        defaultImages: [],
        maxSizeMB: 0.4,
        maxWidthOrHeight: 1920
    });

    // Example upload handler
    const handleFileSelect = async (event: React.ChangeEvent<HTMLInputElement>) => {
        const file = event.target.files?.[0];
        if (file) {
            await handleSingleUpload(file);
        }
    };

    // Example multiple files upload handler
    const handleMultipleFileSelect = async (event: React.ChangeEvent<HTMLInputElement>) => {
        const files = Array.from(event.target.files || []);
        await handleMultipleUpload(files);
    };

    console.log(
        'IPFS Image:', imageData,
        'Loading Image:', isImageLoading,
        'Metadata:', metadata,
        'Loading Metadata:', isMetadataLoading,
        'Uploaded Single Image:', uploadedImage,
        'Single Upload in Progress:', isSingleUploading,
        'Uploaded Multiple Images:', uploadedImages,
        'Multiple Upload in Progress:', isMultipleUploading
    );

    return (
        // Your component JSX here
    );
};

export default ExampleComponent;

/*
Note: These hooks require:
- Valid IPFS gateway configuration
- Network type configuration
- For image hooks:
  - Supported formats: JPEG, PNG, GIF, BMP, TIFF, WebP, SVG
  - Maximum file size: 10MB
- For upload hooks:
  - Default compression to 0.4MB
  - Max width/height: 1920px
  - Web Worker support for compression
*/

Transaction Hooks

The hooks provide tools for handling transactions on VeChain:

Core Transaction Hooks

• useSendTransaction: Core hook for sending any transaction, supporting both Privy and VeChain wallets

• useTransferERC20: Hook for sending ERC20 token transfers

• useTransferVET: Hook for sending native VET token transfers

Types

// Transaction Types
type TransactionStatus = 'ready' | 'pending' | 'waitingConfirmation' | 'success' | 'error';

type TransactionStatusErrorType = {
    type: 'UserRejectedError' | 'RevertReasonError';
    reason: string;
};

type EnhancedClause = {
    to: string;
    value?: string;
    data?: string;
    comment?: string;
    abi?: any;
};

interface TransactionHookReturnValue {
    sendTransaction: () => Promise<void>;
    isTransactionPending: boolean;
    isWaitingForWalletConfirmation: boolean;
    txReceipt: Connex.Thor.Transaction.Receipt | null;
    status: TransactionStatus;
    resetStatus: () => void;
    error?: TransactionStatusErrorType;
}

interface TransferVETParams {
    fromAddress: string;
    receiverAddress: string;
    amount: string;
    onSuccess?: () => void;
    onError?: (error: Error) => void;
}

interface TransferERC20Params {
    fromAddress: string;
    receiverAddress: string;
    amount: string;
    tokenAddress: string;
    tokenName: string;
    onSuccess?: () => void;
    onError?: (error: Error) => void;
}

interface SendTransactionParams {
    signerAccountAddress: string;
    clauses: EnhancedClause[];
    onTxConfirmed?: () => void;
    onTxFailedOrCancelled?: () => void;
}

Usage example

// Example usage of Transaction hooks
import { 
    useSendTransaction,
    useTransferERC20,
    useTransferVET 
} from '@vechain/vechain-kit';

const ExampleComponent = () => {
    // Example of sending VET
    const { 
        sendTransaction: sendVET,
        isTransactionPending: isVETPending,
        status: vetStatus,
        error: vetError 
    } = useTransferVET({
        fromAddress: "0x...",
        receiverAddress: "0x...",
        amount: "1.5",
        onSuccess: () => console.log("VET transfer successful"),
        onError: () => console.log("VET transfer failed")
    });

    // Example of sending ERC20 tokens
    const {
        sendTransaction: sendToken,
        isTransactionPending: isTokenPending,
        status: tokenStatus,
        error: tokenError
    } = useTransferERC20({
        fromAddress: "0x...",
        receiverAddress: "0x...",
        amount: "100",
        tokenAddress: "0x...",
        tokenName: "TOKEN",
        onSuccess: () => console.log("Token transfer successful"),
        onError: () => console.log("Token transfer failed")
    });

    // Example of custom transaction
    const {
        sendTransaction: sendCustomTx,
        isTransactionPending: isCustomPending,
        status: customStatus,
        error: customError
    } = useSendTransaction({
        signerAccountAddress: "0x...",
        clauses: [
            {
                to: "0x...",
                value: "0x0",
                data: "0x...",
                comment: "Custom transaction"
            }
        ],
        onTxConfirmed: () => console.log("Custom transaction successful"),
        onTxFailedOrCancelled: () => console.log("Custom transaction failed")
    });

    const handleVETTransfer = async () => {
        try {
            await sendVET();
        } catch (error) {
            console.error("VET transfer error:", error);
        }
    };

    const handleTokenTransfer = async () => {
        try {
            await sendToken();
        } catch (error) {
            console.error("Token transfer error:", error);
        }
    };

    const handleCustomTransaction = async () => {
        try {
            await sendCustomTx();
        } catch (error) {
            console.error("Custom transaction error:", error);
        }
    };

    return (
        <div>
            <button 
                onClick={handleVETTransfer} 
                disabled={isVETPending}
            >
                Send VET
            </button>
            <button 
                onClick={handleTokenTransfer} 
                disabled={isTokenPending}
            >
                Send Tokens
            </button>
            <button 
                onClick={handleCustomTransaction} 
                disabled={isCustomPending}
            >
                Send Custom Transaction
            </button>

            {/* Status displays */}
            {vetStatus === 'pending' && <div>VET Transfer Pending...</div>}
            {tokenStatus === 'pending' && <div>Token Transfer Pending...</div>}
            {customStatus === 'pending' && <div>Custom Transaction Pending...</div>}

            {/* Error displays */}
            {vetError && <div>VET Error: {vetError.reason}</div>}
            {tokenError && <div>Token Error: {tokenError.reason}</div>}
            {customError && <div>Custom Error: {customError.reason}</div>}
        </div>
    );
};

export default ExampleComponent;

/*
Note: These hooks require:
- Valid thor connection
- Network configuration
- Valid wallet connection
- For ERC20 transfers: valid token contract address
- All amounts should be in their base units (e.g., wei for VET)
*/

Fee Delegation is mostly meant to be implemented to support end-user-experience, removing the need to purchase/collect gas tokens and remove need to pay for the applications activities.

FEE_DELEGATION_URL

You need to set this parameter in your VeChainKitProvider weapper.

You need one per environmnet.

To obtain one you can deploy your own custom solution or use vechain.energy.

Option 1: create your own

You can deploy this as a microservice (through lambda, cloudflare, etc.) or as an endpoint of your backend.

import { Address, HDKey, Transaction, Secp256k1, Hex } from '@vechain/sdk-core';

// the default signer is a solo node seeded account
const DEFAULT_SIGNER = 'denial kitchen pet squirrel other broom bar gas better priority spoil cross'

export async function onRequestPost({ request, env }): Promise<Response> {
    const body = await request.json()
    console.log('Incoming request', body);

    const signerWallet = HDKey.fromMnemonic((env.SIGNER_MNEMONIC ?? DEFAULT_SIGNER).split(' '), HDKey.VET_DERIVATION_PATH).deriveChild(0);
    if (!signerWallet.publicKey || !signerWallet.privateKey) { throw new Error('Could not load signing wallet') }

    const signerAddress = Address.ofPublicKey(signerWallet.publicKey)
    const transactionToSign = Transaction.decode(
        Buffer.from(body.raw.slice(2), 'hex'),
        false
    );
    const transactionHash = transactionToSign.getSignatureHash(Address.of(body.origin))
    const signature = Secp256k1.sign(transactionHash.bytes, signerWallet.privateKey)

    return new Response(JSON.stringify({
        signature: Hex.of(signature).toString(),
        address: signerAddress.toString()
    }), {
        status: 200,
        headers: {
            'Content-Type': 'application/json',
            'access-control-allow-origin': '*'
        }
    })
}

Option 2: use vechain.energy

GO TO TUTORIAL

/// Smart contract to allow delegate all requests

/// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract FeeDelegation {
    /**
     * @dev Check if a transaction can be sponsored for a user
     */
    function canSponsorTransactionFor(
        address _origin,
        address _to,
        bytes calldata _data
    ) public view returns (bool) {
        return true;
    }
}

What is Fee Delegation?

Fee Delegation is a simple process that creates a magical user experience using blockchains without losing decentralized benefits.

The user submitting a transaction requests a second signature from a gas payer.

When the transaction is processed, the gas costs are taken from the gas payers balance instead of the user submitting the transaction.

It creates a feeless and trustless solution for instant blockchain access.

You can read more about it here: https://docs.vechain.org/thor/learn/fee-delegation (opens in a new tab)

Why is it important?

It stops users from instantly using an application. Users that need to pay for transactions are required to obtain a token from somewhere. Regular users do not know where to go and researching a place to buy and accessing a (de)centralized exchange is too much to ask for a user that wants to use your application.

What does it allow?

Users can open an application and interact with it instantly. An Application can submit transactions in the background and can no longer be be distinguished from regular(web2) alternatives. Fee delegation solves the biggest hurdle of user on - boarding to blockchain - applications without invalidating the web3 - principles.

Want to learn more?

You can learn more about the feature from docs.vechain.org on How to Integrate VIP-191 (opens in a new tab).

What are the use-cases?

Fee Delegation is mostly meant to be implemented to support end-user-experience, removing the need to purchase/collect gas tokens and remove need to pay for the applications activities.

Other use-cases are instant interactions with blockchains from different backends or processes without introducing account management for gas tokens.

This document lists all hooks, modules, and features that have been completely removed in v2. If you use any of these, you'll need to find alternatives or implement custom solutions.

Core Hooks Removed

VeBetterDAO Module (Completely Removed)

The entire VeBetterDAO module has been removed. All hooks under api/vebetterdao/ are no longer available.