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: https://docs.privy.io/reference/sdk/server-auth/classes/PrivyClient#importuser

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.

Migrating Your App: From DAppKit or a Traditional Web2 Application

Follow these steps to seamlessly transition your application from DAppKit or a classic web2 framework.

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

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.

Quick Links

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

• Discord: https://discord.com/invite/vechain

• GitHub Issues: https://github.com/vechain/vechain-kit/issues

Common Issue Categories

🔄 Migration Issues

Problems when upgrading from DApp Kit or managing dependencies

• Peer Dependencies

• From DApp Kit

🎨 Styling Issues

CSS conflicts and theming problems

• Chakra UI Conflicts

• CSS Framework Conflicts

⚙️ Integration Issues

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 GitHub Issues or ask on Discord.

VeDelegate Hooks

The hooks provide tools for interacting with VeDelegate token and functionality:

Token Hooks

• useGetVeDelegateBalance: Retrieves the VeDelegate token balance for a given address

Usage Example

// Example usage of VeDelegate hooks
import { useGetVeDelegateBalance } from '@vechain/vechain-kit';

const ExampleComponent = () => {
    const userAddress = "0x..."; // User's wallet address

    // Get VeDelegate token balance
    const { data: veDelegateBalance, isLoading } = useGetVeDelegateBalance(userAddress);

    console.log(
        'VeDelegate Balance:',
        veDelegateBalance,
        'Loading:',
        isLoading
    );

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

export default ExampleComponent;

/*
Note: The VeDelegate balance query will only be enabled when:
- A valid thor connection is available
- A valid address is provided
- A valid network type is configured

The balance is returned as a string representing the token amount.
*/

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.

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:

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:

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

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

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

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

In 2.0 we replaced connex with sdk.

useConnex() is not exported anymore, in favour of useThor() and the signer object can be used to sign transactions following the SDK patterns.

It might require to rm -rf node_modules yarn.lock && yarn

useCallClause hook now provides type safe contract call clause with return types.

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

Where you using any of those hooks? Please reach us on Github to add them back

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:

npm uninstall @vechain/dapp-kit @vechain/dapp-kit-react @vechain/dapp-kit-ui

1. Completely Remove DApp Kit Packages

VeChain Kit provides similar functionality with updated component names:

// X Old DApp Kit
import { ConnectWallet } from '@vechain/dapp-kit-react';

// ✅ New VeChain Kit
import { WalletButton } from '@vechain/vechain-kit';

1. Clean Installation

After removing old packages:

rm -rf node_modules package-lock.json
npm install

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

1) Install package

yarn add @tanstack/react-query@"^5.64.2" @chakra-ui/react@"^2.8.2" @vechain/dapp-kit-react@"2.1.0-rc.1" @vechain/vechain-kit

// or

npm i @tanstack/react-query@"^5.64.2" @chakra-ui/react@"^2.8.2" @vechain/dapp-kit-react@"2.1.0-rc.1" @vechain/vechain-kit

2) Define Provider

'use client';

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

export function VeChainKitProviderWrapper({children}: any) {
  return (
    <VeChainKitProvider
      feeDelegation={{
        delegatorUrl: "https://sponsor-testnet.vechain.energy/by/441",
        // set to false if you want to delegate ONLY social login transactions
        // social login transactions sponsorship is currently mandatory
        delegateAllTransactions: false,
      }}
      loginMethods={[
        {method: "vechain", gridColumn: 4},
        {method: "dappkit", gridColumn: 4},
      ]}
      dappKit={{
        allowedWallets: ["veworld", "wallet-connect", "sync2"],
        walletConnectOptions: {
          projectId:
            // Get this on https://cloud.reown.com/sign-in
            process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
          metadata: {
            name: "React Dapp Template",
            description: "This is the description of your app visible in VeWorld upon connection request.",
            url: typeof window !== "undefined" ? window.location.origin : "",
            icons: ["https://path-to-logo.png"],
          },
        },
      }}
      darkMode={false}
      language="en"
      network={{
        type: "test",
      }}
    >
      {children}
    </VeChainKitProvider>
  );
}

On Next.js you will need to dynamically load the import

import dynamic from 'next/dynamic';

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

Login Methods

The modal implements a dynamic grid layout system that can be customized through the loginMethods configuration.

The modal can be configured through the VeChainKitProvider props.

<VeChainKitProvider
    loginModalUI={{
        logo: '/your-logo.png',
        description: 'Custom login description',
    }}
    loginMethods={[
        { method: 'vechain', gridColumn: 4 },
        { method: 'dappkit', gridColumn: 4 }, // VeChain wallets, always available
        { method: 'ecosystem', gridColumn: 4 }, // Mugshot, Cleanify, Greencart, ...
        { method: 'email', gridColumn: 2 }, // only available with your own Privy
        { method: 'passkey', gridColumn: 2 },  // only available with your own Privy
        { method: 'google', gridColumn: 4 }, // only available with your own Privy
        { method: 'more', gridColumn: 2 }, // will open your own Privy login, only available with your own Privy
        
    ]}
    allowCustomTokens={false} // allow the user to manage custom tokens
>
    {children}
</VeChainKitProvider>

// This will show a type error
const invalidConfig: VechainKitProviderProps = {
    // no privy prop specified
    loginMethods: [
        { method: 'email' }  // ❌ Type error: 'email' is not assignable to type 'never'
    ],
    // ... other required props
};

// This is valid
const validConfig1: VechainKitProviderProps = {
    // no privy prop
    loginMethods: [
        { method: 'vechain' },  // ✅ OK
        { method: 'dappkit' },  // ✅ OK
        { method: 'ecosystem' } // ✅ OK
    ],
    // ... other required props
};

// This is also valid
const validConfig2: VechainKitProviderProps = {
    privy: {
        appId: 'xxx',
        clientId: 'yyy',
        // ... other privy props
    },
    loginMethods: [
        { method: 'email' },     // ✅ OK because privy is configured
        { method: 'google' },    // ✅ OK because privy is configured
        { method: 'vechain' },   // ✅ OK (always allowed)
        { method: 'ecosystem' }  // ✅ OK (always allowed)
    ],
    // ... other required props
};

3) Setup Fee Delegation (mandatory if allowing social login)

Fee delegation is mandatory if you want to use this kit with social login. Learn how to setup fee delegation in the following guide:

4) Setup Privy (optional)

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();

5) Setup Legal Documents (optional)

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

6) Show the login button

Once you set up the kit provider, you are good to go, and you can allow your users to login, customizing the login experience based on your needs. You can choose between many options, leaving you complete freedom on your design.

'use client';

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

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

'use client';

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

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

// Example usage of Login hooks
import { 
    useLoginWithOAuth,
} from '@vechain/vechain-kit';

const ExampleComponent = () => {
    // OAuth authentication
    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>
            {/* OAuth Login Options */}
            <button onClick={() => handleOAuthLogin('google')}>
                Login with Google
            </button>
            <button onClick={() => handleOAuthLogin('twitter')}>
                Login with Twitter
            </button>
            <button onClick={() => handleOAuthLogin('apple')}>
                Login with Apple
            </button>
            <button onClick={() => handleOAuthLogin('discord')}>
                Login with Discord
            </button>
        </div>
    );
};

export default ExampleComponent;

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

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

  return (
    <Button onClick={openWalletModal}>
        Open only "Connect Wallet"
    </Button>
)}

Support for devs

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

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

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

Hooks

The hooks offer tools for efficient smart account management:

• useGetAccountAddress: Retrieves the smart account's address linked to the wallet.

• useGetAccountVersion: Retrieces the smart account's version even if the account is not deployed yet

• useSmartAccountVersion: Retrieves the smart account's version, but only if it is already deployed, and it will revert for v1 smart accounts (because function was not implemented in that smart contract)

• useSmartAccount: Retrieves the the account of an owner, returning additional information

• useAccountImplementationAddress: Returns the implementation address of a specific version; this hook is useful when upgrading the smart account of the user

• useCurrentAccountImplementationVersion: Returns the latest (and currently used) implementation version of the smart accounts used by the factory

• useUpgradeRequired: Returns if a smart account needs an upgrade (even if it's not yet deployed)

• useUpgradeRequiredForAccount: As above but only if the account is not yet deployed

• useIsSmartAccountDeployed: Verifies the deployment status of the smart account.

• useHasV1SmartAccount: Checks for a legacy version's existence.

• useUpgradeSmartAccount: Hook to create a transaction to upgrade the smart account to a specific version

Usage

useCurrentBlock()

Fetches the current block from the blockchain with automatic updates.

Features:

• Auto-refreshes every 10 seconds

• Caches data for 1 minute

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

Example:

useTxReceipt()

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

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:

Utility Functions

getEvents()

Fetches events from the blockchain based on specified criteria.

getAllEvents()

Iteratively fetches all events matching the criteria, handling pagination automatically.

Parameters for getEvents/getAllEvents:

• nodeUrl: VeChain node URL

• thor: Thor client instance

• filterCriteria: Array of event filter criteria

• order: Sort order ('asc' or 'desc')

• from: Starting block number

• to: Ending block number

• offset: (getEvents only) Number of events to skip

• limit: (getEvents only) Maximum number of events to return

These hooks and functions are designed to work with the VeChain blockchain and require the VeChain Kit context to be properly set up in your application.

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

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:

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

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 .

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.

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

// NFT Types
interface NFTMetadata {
    name: string;
    description: string;
    image: string;
    attributes: {
        trait_type: string;
        value: string | number;
    }[];
}

interface NFTImageHookParams {
    address: string;
    contractAddress: string;
}

interface NFTMetadataUriParams {
    tokenId: string;
    contractAddress: string;
}

interface NFTImageHookResult {
    imageData: string | null;
    imageMetadata: NFTMetadata | null;
    tokenID: string | null;
    isLoading: boolean;
    error: Error | null;
}

interface NFTMetadataUriResult {
    data: string | null;
    isLoading: boolean;
    error: Error | null;
}

Example usage

// Example usage of NFT hooks
import { useNFTImage, useNFTMetadataUri } from '@vechain/vechain-kit';

const ExampleComponent = () => {
    const walletAddress = "0x...";
    const tokenId = "1";
    const contractAddress = "0x...";

    // Get complete NFT data including image
    const { 
        imageData,
        imageMetadata,
        tokenID,
        isLoading: isLoadingNFT,
        error: nftError 
    } = useNFTImage({
        address: walletAddress,
        contractAddress: contractAddress
    });

    // Get just the metadata URI
    const {
        data: metadataUri,
        isLoading: isLoadingUri,
        error: uriError
    } = useNFTMetadataUri({
        tokenId,
        contractAddress
    });

    // Handle loading states
    if (isLoadingNFT || isLoadingUri) {
        return <div>Loading NFT data...</div>;
    }

    // Handle errors
    if (nftError || uriError) {
        return <div>Error: {nftError?.message || uriError?.message}</div>;
    }

    console.log(
        'NFT Image:', imageData,
        'NFT Metadata:', imageMetadata,
        'Token ID:', tokenID,
        'Metadata URI:', metadataUri
    );

    // Example of using the NFT data
    return (
        <div>
            {imageData && (
                <img 
                    src={imageData} 
                    alt={imageMetadata?.name || 'NFT'} 
                />
            )}
            {imageMetadata && (
                <div>
                    <h2>{imageMetadata.name}</h2>
                    <p>{imageMetadata.description}</p>
                    {imageMetadata.attributes?.map((attr, index) => (
                        <div key={index}>
                            {attr.trait_type}: {attr.value}
                        </div>
                    ))}
                </div>
            )}
        </div>
    );
};

export default ExampleComponent;

/*
Note: These hooks require:
- Valid thor connection
- Network type configuration
- Valid IPFS gateway for image fetching
- The hooks handle the complete flow:
  1. Get token ID from address
  2. Get metadata URI from token ID
  3. Fetch metadata from IPFS
  4. Fetch image from IPFS

Types:
interface NFTMetadata {
    name: string;
    description: string;
    image: string;
    attributes: {
        trait_type: string;
        value: string;
    }[];
}
*/

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,
                }}
            />
        </>
    );
}

The hooks provide tools for managing various modals in the VeChain application:

Account Related Modals

• useAccountModal: Core account modal management

• useProfileModal: Show the user only his profile, with customize and logout option

• useAccountCustomizationModal: Account customization settings

• useAccessAndSecurityModal: Security settings and access management

• useChooseNameModal: Account name selection

• useUpgradeSmartAccountModal: Smart account upgrade management

Wallet & Connection Modals

• useConnectModal: Wallet connection modal

• useWalletModal: Combined wallet management modal

• useLoginModalContent: Login modal content configuration

Transaction Modals

• useTransactionModal: Transaction confirmation and status

• useTransactionToast: Transaction notifications

• useSendTokenModal: Token transfer interface

• useReceiveModal: Token receiving interface

Additional Feature Modals

• useExploreEcosystemModal: VeChain ecosystem explorer

• useNotificationsModal: Notification center

• useFAQModal: Frequently asked questions

Types

Usage example

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

The useWallet hook provides a unified interface for managing wallet connections in a VeChain application, supporting multiple connection methods including social logins (via Privy), direct wallet connections (via DappKit), and cross-application connections.

This will be the hook you will use more frequently and it provides quite a few useful informations.

Usage

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

function MyComponent = () => {
    const {
        account,
        connectedWallet,
        smartAccount,
        privyUser,
        connection,
        disconnect
    } = useWallet();
    
    return <></>
}

Types

export type Wallet = {
    address: string;
    domain?: string;
    image: string;
} | null;

export type SmartAccount = Wallet & {
    isDeployed: boolean;
    isActive: boolean;
    version: string | null;
};

export type ConnectionSource = {
    type: 'privy' | 'wallet' | 'privy-cross-app';
    displayName: string;
};

interface User {
    /** The Privy-issued DID for the user. If you need to store additional information
     * about a user, you can use this DID to reference them. */
    id: string;
    /** The datetime of when the user was created. */
    createdAt: Date;
    /** The user's email address, if they have linked one. It cannot be linked to another user. */
    email?: Email;
    /** The user's phone number, if they have linked one. It cannot be linked to another user. */
    phone?: Phone;
    /** The user's most recently linked wallet, if they have linked at least one wallet.
     *  It cannot be linked to another user.
     *  This wallet is the wallet that will be used for transactions and signing if it is connected.
     **/
    wallet?: Wallet;
    /**
     * The user's smart wallet, if they have set up through the Privy Smart Wallet SDK.
     */
    smartWallet?: SmartWallet;
    /** The user's Google account, if they have linked one. It cannot be linked to another user. */
    google?: Google;
    /** The user's Twitter account, if they have linked one. It cannot be linked to another user. */
    twitter?: Twitter;
    /** The user's Discord account, if they have linked one. It cannot be linked to another user. */
    discord?: Discord;
    /** The user's Github account, if they have linked one. It cannot be linked to another user. */
    github?: Github;
    /** The user's Spotify account, if they have linked one. It cannot be linked to another user. */
    spotify?: Spotify;
    /** The user's Instagram account, if they have linked one. It cannot be linked to another user. */
    instagram?: Instagram;
    /** The user's Tiktok account, if they have linked one. It cannot be linked to another user. */
    tiktok?: Tiktok;
    /** The user's LinkedIn account, if they have linked one. It cannot be linked to another user. */
    linkedin?: LinkedIn;
    /** The user's Apple account, if they have linked one. It cannot be linked to another user. */
    apple?: Apple;
    /** The user's Farcaster account, if they have linked one. It cannot be linked to another user. */
    farcaster?: Farcaster;
    /** The user's Telegram account, if they have linked one. It cannot be linked to another user. */
    telegram?: Telegram;
    /** The list of accounts associated with this user. Each account contains additional metadata
     * that may be helpful for advanced use cases. */
    linkedAccounts: Array<LinkedAccountWithMetadata>;
    /** The list of MFA Methods associated with this user. */
    mfaMethods: Array<MfaMethod>;
    /**
     * Whether or not the user has explicitly accepted the Terms and Conditions
     * and/or Privacy Policy
     */
    hasAcceptedTerms: boolean;
    /** Whether or not the user is a guest */
    isGuest: boolean;
    /** Custom metadata field for a given user account */
    customMetadata?: CustomMetadataType;
}

Return values

account: Wallet

The primary account being used. This will be either:

• The smart account (if connected via Privy)

• The wallet address (if connected via DappKit)

smartAccount: SmartAccount

Information about the user's smart account:

• address: The smart account address

• domain: Associated VeChain domain name

• image: Generated avatar image

• isDeployed: Whether the smart account is deployed; smart accounts can be deployed on demand to avoid spending money on non active users. Learn more about smart accounts here.

• isActive: Whether this is the currently active account

• version: Smart account contract version

When the user is connected with Privy account will always be equal to the smartAccount.

connectedWallet: Wallet

The currently connected wallet, regardless of connection method (can be both a Privy Embedded Wallet or a self custody Wallet connected trough VeWorld or Sync2):

• address: Wallet address

• domain: Associated VeChain domain name

• image: Generated avatar image

privyUser: User | null

The Privy user object if connected via Privy, null otherwise

connection: ConnectionState

Current connection state information:

• isConnected: Overall connection status

• isLoading: Whether connection is in progress

• isConnectedWithSocialLogin: Connected via Privy (no crossapp)

• isConnectedWithDappKit: Connected via DappKit

• isConnectedWithCrossApp: Connected via cross-app

• isConnectedWithPrivy: Connected via Privy (social or cross-app)

• isConnectedWithVeChain: Connected with VeChain cross-app

• source: Connection source information

• isInAppBrowser: Whether your app is running in VeWorld app browser

• nodeUrl: Current node URL (if provided by you in the provider, otherwise default in use by VeChain Kit)

• delegatorUrl: Fee delegation service URL setted by you in the provider

• chainId: Current chain ID

• network: Network type (mainnet/testnet/custom)

disconnect(): Promise<void>

This function terminates the current wallet connection, ensuring cleanup of connection details and triggering necessary event listeners for state updates.

Connection Sources

The hook supports three main connection types:

1. Social Login (privy): Authentication via social providers with your own APP_ID

2. Wallet Connection (wallet): Direct wallet connection via DappKit

3. Cross-App (privy-cross-app): Connection through ecosystem integration

Events

The hook dispatches a wallet_disconnected event when the wallet is disconnected, which can be used to trigger UI updates in dependent components.

Type Safety

// ✅ Good: Proper typing
const args: [string, bigint, boolean] = [address, amount, isEnabled];
const contractAddress = config.contractAddress as `0x${string}`;
const method = 'balanceOf' as const;

// ✅ Use contract factories
import { VOT3__factory } from '@vechain/vechain-kit/contracts';
const abi = VOT3__factory.abi;

// Avoid: Manual ABI definitions
const functionAbi = contractAbi.find((e) => e.name === "delegates");

Query Optimization

// ✅ Good: Conditional enablement
return useCallClause({
  abi,
  address: contractAddress,
  method: 'getData',
  args: [userAddress],
  queryOptions: {
    enabled: !!contractAddress && !!userAddress && isConnected,
  },
});

// ✅ Good: Configure caching
queryOptions: {
  staleTime: 30000,        // 30 seconds for price data
  refetchInterval: 60000,  // Refetch every minute
}

Data Transformation

// ✅ Good: Transform in select
return useCallClause({
  abi: VOT3__factory.abi,
  address: contractAddress,
  method: 'convertedB3trOf' as const,
  args: [address ?? ''],
  queryOptions: {
    enabled: !!address,
    select: (data) => ({
      balance: ethers.formatEther(data[0]),
      formatted: humanNumber(ethers.formatEther(data[0])),
    }),
  },
});

// Avoid: Transform in component
const transformedData = useMemo(() => ({
  balance: data?.[0]?.toString(),
}), [data]); // Causes re-renders

Error Handling

// ✅ Good: Comprehensive error handling
if (error) {
  if (error.message.includes('reverted')) {
    return <div>Contract call failed. Check parameters.</div>;
  }
  if (error.message.includes('network')) {
    return <div>Network error. <button onClick={refetch}>Retry</button></div>;
  }
  return <div>Error: {error.message}</div>;
}

// ✅ Good: Retry logic
queryOptions: {
  retry: (failureCount, error) => {
    if (error.message.includes('reverted')) return false;
    return failureCount < 3;
  },
  retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
}

Query Key Management

// ✅ Good: Use getCallClauseQueryKey (without args) 
export const getCurrentAllocationsRoundIdQueryKey = (
  address: string,
  networkType: NETWORK_TYPE
) =>
  getCallClauseQueryKey({
    abi: XAllocationVoting__factory.abi,
    address: getConfig(networkType).contractAddress as `0x${string}`,
    method: 'currentRoundId' as const,
  });
  
// ✅ Good: Use getCallClauseQueryKeyWithArgs
export const getTokenBalanceQueryKey = (
  address: string,
  networkType: NETWORK_TYPE
) =>
  getCallClauseQueryKeyWithArgs({
    abi: VOT3__factory.abi,
    address: getConfig(networkType).contractAddress as `0x${string}`,
    method: 'balanceOf' as const,
    args: [address],
  });

// ✅ Good: Query invalidation after transactions
const mutation = useBuildTransaction({
  clauseBuilder: buildClauses,
  onTxConfirmed: () => {
    queryClient.invalidateQueries({ queryKey: getTokenBalanceQueryKey(userAddress, networkType) });
  },
});

Performance Tips

// ✅ Good: Memoize expensive calculations
const queryKey = useMemo(() => 
  getTokenBalanceQueryKey(userAddress, tokenAddress),
  [userAddress, tokenAddress]
);

// ✅ Good: Batch multiple calls
const results = await executeMultipleClausesCall({
  thor,
  calls: addresses.map((address) => ({
    abi: ERC20__factory.abi,
    functionName: 'balanceOf',
    address: address as `0x${string}`,
    args: [userAddress],
  })),
});

Security

// ✅ Good: Input validation
if (!isAddress(recipient)) {
  throw new Error('Invalid recipient address');
}

const amountBN = BigInt(amount);
if (amountBN <= 0n) {
  throw new Error('Amount must be positive');
}

// ✅ Good: Safe BigInt handling
const formatTokenAmount = (amount: bigint, decimals: number): string => {
  try {
    return ethers.formatUnits(amount, decimals);
  } catch (error) {
    return '0';
  }
};

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.

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

Available imports

• @vechain/vechain-kit

• @vechain/vechain-kit/utils

• @vechain/vechain-kit/contracts

• @vechain/vechain-kit/assets

Update Dependencies

Deprecated/Removed Hooks

Update Imports

Update Contract Calls

Reading Data

Writing Data (Transactions)

Key Patterns

Type Safety

Query Enablement

Error Handling

Next Steps

1. Review for detailed interaction examples

2. Apply for optimal performance

3. Verify all functionality works as expected

4. Consult for common issues

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 (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:

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 button acts both as a login button and as an account button (when the user is already logged).

VeChain Kit provides multiple ways to customize the UI components. Here are some examples of different button styles and variants.

Usage example

'use client';

import { VStack, Text, Button, Box, HStack, Grid } from '@chakra-ui/react';
import {
    WalletButton,
    useAccountModal,
    ProfileCard,
    useWallet,
} from '@vechain/vechain-kit';
import { MdBrush } from 'react-icons/md';
import { CollapsibleCard } from '../../ui/CollapsibleCard';

export function UIControls() {
    const { open } = useAccountModal();
    const { account } = useWallet();

    return (
        <>
            <VStack spacing={6} align="stretch" w={'full'}>
                <Text textAlign="center">
                    VeChain Kit provides multiple ways to customize the UI
                    components. Here are some examples of different button
                    styles and variants.
                </Text>

                <HStack w={'full'} justifyContent={'space-between'}>
                    {/* Mobile Variants */}
                    <HStack w={'full'} justifyContent={'center'}>
                        <VStack
                            w={'fit-content'}
                            spacing={6}
                            p={6}
                            borderRadius="md"
                            bg="whiteAlpha.50"
                        >
                            <Text fontWeight="bold">
                                Account Button Variants
                            </Text>
                            <Text
                                fontSize="sm"
                                textAlign="center"
                                color="gray.400"
                            >
                                Note: Some variants might look different based
                                on connection state and available data. Eg:
                                "iconDomainAndAssets" will show the assets only
                                if the user has assets. And same for domain
                                name.
                            </Text>
                            <Grid
                                templateColumns={{
                                    base: '1fr',
                                    md: 'repeat(2, 1fr)',
                                }}
                                gap={8}
                                w="full"
                                justifyContent="space-between"
                            >
                                {/* First Column Items */}
                                <VStack alignItems="flex-start" spacing={8}>
                                    <VStack alignItems="flex-start" spacing={2}>
                                        <Box w={'fit-content'}>
                                            <WalletButton
                                                mobileVariant="icon"
                                                desktopVariant="icon"
                                            />
                                        </Box>
                                        <Text
                                            fontSize="sm"
                                            fontWeight="medium"
                                            color="blue.300"
                                            bg="whiteAlpha.100"
                                            px={3}
                                            py={1}
                                            borderRadius="full"
                                        >
                                            variant: "icon"
                                        </Text>
                                    </VStack>

                                    <VStack alignItems="flex-start" spacing={2}>
                                        <Box w={'fit-content'}>
                                            <WalletButton
                                                mobileVariant="iconAndDomain"
                                                desktopVariant="iconAndDomain"
                                            />
                                        </Box>
                                        <Text
                                            fontSize="sm"
                                            fontWeight="medium"
                                            color="blue.300"
                                            bg="whiteAlpha.100"
                                            px={3}
                                            py={1}
                                            borderRadius="full"
                                        >
                                            variant: "iconAndDomain"
                                        </Text>
                                    </VStack>

                                    <VStack alignItems="flex-start" spacing={2}>
                                        <Box w={'fit-content'}>
                                            <WalletButton
                                                mobileVariant="iconDomainAndAddress"
                                                desktopVariant="iconDomainAndAddress"
                                            />
                                        </Box>
                                        <Text
                                            fontSize="sm"
                                            fontWeight="medium"
                                            color="blue.300"
                                            bg="whiteAlpha.100"
                                            px={3}
                                            py={1}
                                            borderRadius="full"
                                        >
                                            variant: "iconDomainAndAddress"
                                        </Text>
                                    </VStack>
                                </VStack>

                                {/* Second Column Items */}
                                <VStack alignItems={'flex-start'} spacing={8}>
                                    <VStack alignItems="flex-start" spacing={2}>
                                        <Box w={'fit-content'}>
                                            <WalletButton
                                                mobileVariant="iconDomainAndAssets"
                                                desktopVariant="iconDomainAndAssets"
                                            />
                                        </Box>
                                        <Text
                                            fontSize="sm"
                                            fontWeight="medium"
                                            color="blue.300"
                                            bg="whiteAlpha.100"
                                            px={3}
                                            py={1}
                                            borderRadius="full"
                                        >
                                            variant: "iconDomainAndAssets"
                                        </Text>
                                    </VStack>

                                    <VStack alignItems="flex-start" spacing={2}>
                                        <Box w={'fit-content'}>
                                            <WalletButton
                                                mobileVariant="iconDomainAndAssets"
                                                desktopVariant="iconDomainAndAssets"
                                                buttonStyle={{
                                                    border: '2px solid #000000',
                                                    boxShadow:
                                                        '-2px 2px 3px 1px #00000038',
                                                    background: '#f08098',
                                                    color: 'white',
                                                    _hover: {
                                                        background: '#db607a',
                                                        border: '1px solid #000000',
                                                        boxShadow:
                                                            '-3px 2px 3px 1px #00000038',
                                                    },
                                                    transition: 'all 0.2s ease',
                                                }}
                                            />
                                        </Box>
                                        <Text
                                            fontSize="sm"
                                            fontWeight="medium"
                                            color="blue.300"
                                            bg="whiteAlpha.100"
                                            px={3}
                                            py={1}
                                            borderRadius="full"
                                        >
                                            variant: "iconDomainAndAssets"
                                            (styled)
                                        </Text>
                                    </VStack>

                                    <VStack alignItems="flex-start" spacing={2}>
                                        <Button onClick={open}>
                                            <Text>This is a custom button</Text>
                                        </Button>
                                        <Text
                                            fontSize="sm"
                                            fontWeight="medium"
                                            color="blue.300"
                                            bg="whiteAlpha.100"
                                            px={3}
                                            py={1}
                                            borderRadius="full"
                                        >
                                            no variant, custom button
                                        </Text>
                                    </VStack>
                                </VStack>
                            </Grid>
                        </VStack>
                    </HStack>
                </HStack>
            </VStack>
        </>
    );
}

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.

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

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

  return (
    <Button onClick={openWalletModal}>
        Open only "Connect Wallet"
    </Button>
)}

Our are a simplified version of the Account Abstraction pattern, made for the VeChain blockchain, and are required in order to enable social login.

Addresses

Mainnet

Testnet

Contracts

There are 2 contracts that work together to enable social login and account abstraction:

• SimpleAccount: A smart contract wallet owned by the user that can:

  • Execute transactions directly from the owner or through signed messages

  • Handle both single and batch transactions

• SimpleAccountFactory: Factory contract that creates and manages SimpleAccount contracts:

  • Creates new accounts with deterministic addresses using CREATE2

  • Get the account address of a smart account without deploying it

  • Supports multiple accounts per owner through custom salts

  • Manages different versions of the SimpleAccount implementation

How it works

1. Account Creation: When a user wants to create a smart account, they interact with the SimpleAccountFactory, which creates a new SimpleAccount instance with the user as the owner.

2. Transaction Execution: The SimpleAccount can execute transactions in several ways:

   • Direct execution by the owner

   • Batch execution of multiple transactions

   • Signature-based execution (useful for social login) - Deprecated, should avoid using this

   • Batch signature-based execution with replay protection (useful for social login + multiclause)

   • Batch signature-based execution with 16-bit chain ID to allow iOS and Android developers handle VeChain chain ID.

3. Nonce Management: For batch transactions with authorization (executeBatchWithAuthorization), a nonce is required to protect users against replay attacks:

   • The nonce should be generated when requesting the signature

   • Best practice is to use Date.now() as the nonce value

   • Each nonce can only be used once per account

   • Without proper nonce management, malicious actors could replay the same signed transaction multiple times

   • Nonces are only used and required for executeBatchWithAuthorization method

4. Social Login Integration: This system enables social login by creating deterministic account addresses for each user and allowing transactions to be signed off-chain and executed by anyone. This creates a seamless experience where users can interact with dApps using their social credentials.

Version Management

The system has evolved through multiple versions to improve functionality and security:

• SimpleAccount:

  • V1: Basic account functionality with single transaction execution

  • V2: Skipped for misconfiguration during upgrade

  • V3: Introduced batch transactions with nonce-based replay protection, ownership transfer and version tracking

• SimpleAccountFactory:

  • V1: Basic account creation and management

  • V2: Added support for multiple accounts per owner using custom salts

  • V3: Support for V3 SimpleAccounts, enhanced version management and backward compatibility with legacy accounts

The factory maintains compatibility with all account versions, ensuring a smooth experience across different dApps and versions.

Smart Accounts V3 upgrade

Upgrading the user's smart accounts from V1 to V3 is mandatory, in order to protect against reply attacks and to allow multiclause transactions on VeChain.

To facilitate the mandatory upgrade process, the kit now includes:

• Built-in Check: Automatically displays an alert prompting users to upgrade if they possess a V1 smart account.

• Hooks & Component: To avoid apps spending VTHO to upgrade accounts of users that won't do any action on the app we allow the developer to check upgradeability on demand by using the useUpgradeRequiredForAccount hook and show the UpgradeSmartAccountModal (importable from the kit).

Hooks

Developers can efficiently manage smart accounts using a provided by the kit.

By importing these hooks, developers can:

• Easily check if an upgrade is needed

• Determine the current smart account version

• Simplify maintaining and upgrading smart accounts

This ensures users seamlessly benefit from the latest features and protections.

Multiclause transactions

Multiclause transactions offer enhanced security and flexibility within the VeChain ecosystem. Here's a breakdown of the key points for developers:

• Single Clause Transactions: You can still use executeWithAuthorization, but keep in mind it retains a replay attack vector. This method is primarily for backward compatibility.

• Recommended Adoption: Switch to executeBatchWithAuthorization for a more secure solution. This method:

  • Solves replay attack issues.

  • Executes multiple transactions with a single signature, simulating multiclause capabilities.

• Automatic Management: Using useSendTransaction from the kit automates this process, negating the need for manual adjustments.

Understanding these components is crucial for those working with smart accounts outside of the vechain-kit. This knowledge ensures both security and operational efficiency.

How to use executeBatchWithAuthorization and the nonce :

VeBetterDAO Hooks

The hooks provide tools for interacting with VeBetterDAO's smart contracts and features:

Galaxy Member Hooks

• useB3trDonated: Fetches the amount of B3TR tokens donated for a given token ID

• useB3trToUpgrade: Retrieves the amount of B3TR tokens required to upgrade a specific token

• useB3trToUpgradeToLevel: Gets the amount of B3TR needed to upgrade to a specific level

• useGMBaseUri: Retrieves the base URI for the Galaxy Member NFT metadata

• useGMMaxLevel: Fetches the maximum level possible for Galaxy Member NFTs

• useGMbalance: Gets the number of GM NFTs owned by an address

• useGetNodeIdAttached: Retrieves the Vechain Node Token ID attached to a given GM Token ID

• useGetTokenIdAttachedToNode: Gets the GM Token ID attached to a given Vechain Node ID

• useGetTokensInfoByOwner: Fetches token information for a specific owner with infinite scrolling support

• useIsGMclaimable: Determines if a user can claim a GM NFT

• useLevelMultiplier: Gets the reward multiplier for a specific GM level

• useLevelOfToken: Retrieves the level of a specified token

• useParticipatedInGovernance: Checks if an address has participated in governance

• useSelectedGmNft: Comprehensive hook for retrieving data related to a Galaxy Member NFT

• useSelectedTokenId: Gets the selected token ID for the selected galaxy member

• useTokenIdByAccount: Retrieves the token ID for an address given an index

Node Management Hooks

• useGetNodeManager: Gets the address of the user managing a node ID (endorsement) either through ownership or delegation

Rewards Hooks

• useVotingRewards: Manages voting rewards functionality

• useVotingRoundReward: Handles rewards for specific voting rounds

Usage Example

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:

Best Practices

1. Load Data Early

1. Show Loading States

1. Avoid Async in Click Handlers

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

When a user initiates a connection through Privy, either directly or via cross-app integration, a secure wallet is immediately created for them. Privy implements a sophisticated key management technique known as key splitting, specifically using Shamir’s secret sharing method. This approach ensures that users retain full custody of their wallets without needing to manage any secret keys themselves. Importantly, neither Privy nor any integrated application ever accesses the user's keys; these secrets are only reconstituted directly on the user's device during the signing of messages or transactions. This process guarantees the utmost security and privacy for the user's onchain activities.

This type of wallet created by Privy is called Embedded Wallet.

Seamless Wallet Integration

Users benefit from an intuitively integrated wallet management experience that aligns seamlessly with their existing accounts, removing any unnecessary technical barriers. Applications built with Privy can generate wallets automatically for new accounts, such as those registered with an email address or phone number, even before the user logs in for the first time. Additionally, Privy provides users with the option to export their wallet keys, serving as an escape mechanism should they choose to transition away from Privy’s services at any point.

Using wallets across apps

Privy embedded wallets are portable and can be used by any app––even apps not using Privy. Privy’s cross application wallet system supports interoperability with simple user experiences accessible to everyone, and seamlessly integrates with other Privy integrations and wallet connector solutions like RainbowKit and wagmi.

Embedded wallets can be backed up by the user through the VeChain Kit modal in the Settings page.

Many login methods can be attached to the Embedded Wallet.

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

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:

Next Steps

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

2. Review to understand new interaction methods

3. Apply for optimal performance

4. Consult if you encounter issues