@vechain/vechain-kit 1.2.2 → 1.2.3

package/README.md

@@ -6,21 +6,26 @@
     <img src="https://i.ibb.co/k539SN7/kit-banner.png" alt="VeChain Kit Banner">
 </div>
 
-# Features
+VeChain Kit is a comprehensive library designed to make building VeChain applications fast and straightforward.
 
--   🔌 **Wallet Connection**: VeWorld, Sync2, WalletConnect, VeChain Embedded Wallet, Social Login (Privy)
--   🪝 **React Hooks**: Read and write to the VeChainThor blockchain
--   🧩 **Components**: Pre-built components for wallet operations
--   🌍 **Multilanguage**: Built-in i18n support
--   💰 **Token Operations**: Send tokens, check balances, handle VET domains, and more
+It offers:
+
+-   <b>Seamless Wallet Integration:</b> Support for VeWorld, Sync2, WalletConnect, VeChain Embedded Wallet, and social logins (powered by Privy).
+-   <b>Unified Ecosystem Accounts:</b> Leverage Privy’s Ecosystem feature to give users a single wallet across multiple dApps, providing a consistent identity within the VeChain network.
+-   <b>Developer-Friendly Hooks:</b> Easy-to-use React Hooks that let you read and write data on the VeChainThor blockchain.
+-   <b>Pre-Built UI Components:</b> Ready-to-use components (e.g., TransactionModal) to simplify wallet operations and enhance your users’ experience.
+-   <b>Multi-Language Support:</b> Built-in i18n for a global audience.
+-   <b>Token Operations:</b> Send tokens, check balances, manage VET domains, and more—all in one place.
 
 > **Note**: Currently supports React and Next.js only
 
-📚 For detailed documentation, visit our [VeChain Kit Docs](https://vechain-foundation-san-marino.gitbook.io/vechain-kit)
+📚 For detailed documentation, visit our [VeChain Kit Docs](https://docs.vechain-kit.vechain.org/)
 
-Try out the [demo app](https://sample-vechain-app-demo.vechain.org/) to see how it works.
+## Demo & Examples
 
-Also check out the [sample app](https://github.com/vechain/vechain-kit/tree/main/examples/tutorial-next) to see how to integrate the library with Next.js.
+-   [Live Demo](https://vechain-kit.vechain.org/)
+-   [Sample Next.js App](https://github.com/vechain/vechain-kit/tree/main/examples/next-template)
+-   [Smart Account Factory](https://vechain.github.io/smart-accounts-factory/)
 
 # Installation
 
@@ -30,40 +35,26 @@ yarn add @tanstack/react-query@"^5.64.2" @chakra-ui/react@"^2.8.2" @vechain/dapp
 
 # Quick Start
 
-## Basic Setup
-
-Import the `VechainKitProvider` provider and wrap your app in it.
+### Define Provider
 
 ```typescript
-import { VechainKitProvider } from '@vechain/vechain-kit';
+'use client';
 
-export default function App({ Component, pageProps }: AppProps) {
+import DAppKitPrivyProvider from '@vechain/dapp-kit-react-privy'
+
+export function DAppKitPrivyProvider({ children }: Props) {
     return (
-        <VechainKitProvider
+         <VechainKitProvider
             // Mandatory
             feeDelegation={{
-                delegatorUrl: process.env.NEXT_PUBLIC_DELEGATOR_URL!,
+                delegatorUrl: process.env.NEXT_PUBLIC_DELEGATOR_URL!
             }}
             dappKit={{
-                allowedWallets: ['veworld', 'wallet-connect', 'sync2'],
-                // If you want to use WalletConnect
-                walletConnectOptions: {
-                    projectId:
-                        process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
-                    metadata: {
-                        name: 'Your App',
-                        description: 'Your app description',
-                        url:
-                            typeof window !== 'undefined'
-                                ? window.location.origin
-                                : '',
-                        icons: [
-                            typeof window !== 'undefined'
-                                ? `${window.location.origin}/images/logo/my-dapp.png`
-                                : '',
-                        ],
-                    },
-                },
+                allowedWallets: ['veworld', 'sync2'],
+            }}
+            privyEcosystemApps=[] // remove for using default ones
+            loginModalUI={{
+                variant: 'vechain-wallet-ecosystem',
             }}
             darkMode={true}
             language="en"
@@ -77,9 +68,44 @@ export default function App({ Component, pageProps }: AppProps) {
 }
 ```
 
-This will allow you to connect to wallets (VeWorld, Sync2, WalletConnect) and to use Social Login trhough VeChain.
+On Next.js you will need to dynamically load the import
+
+```typescript
+import dynamic from 'next/dynamic';
+const VeChainKitProviderWrapper = dynamic(
+    async () => (await import('@vechain/vechain-kit')).VeChainKitProvider,
+    {
+        ssr: false,
+    },
+);
+interface Props {
+    children: React.ReactNode;
+}
+```
+
+### Setup Fee Delegation (mandatory)
+
+Fee delegation is mandatory in order to use this kit. Learn how to setup fee delegation in the following guide:
+
+[Fee Delegation](https://app.gitbook.com/o/PqN0Gs1QEzg8tbeJCHXC/s/S8udqSGhGctlwwL1kst7/~/changes/42/vechain-kit/fee-delegation)
+
+### Setup Privy (optional)
+
+If you already use Privy you can pass an additional prop with you settings and you will be able to access Privy SDK, customizing the login modal based on your needs.
+
+Pros of self hosting Privy:
 
-If you want to have your own Privy app, for enchanced user experience, you can use the `privy` prop.
+-   No UI confirmations on users transactions
+-   Allow your users to backup their keys and update security settings directly in your app
+-   Targetted social login methods
+
+Cons:
+
+-   Price
+-   Responsibilities to correctly secure your Privy account, since it contains access to user's wallet settings
+-   Your users will need to login into other apps through ecosystem mode
+
+To setup Privy you need to add the following parameters:
 
 ```typescript
 import { VechainKitProvider } from '@vechain/vechain-kit';
@@ -103,6 +129,7 @@ export default function App({ Component, pageProps }: AppProps) {
                 allowPasskeyLinking: true,
             }}
             ...
+            //other props
         >
             {children}
         </VechainKitProvider>
@@ -110,83 +137,146 @@ export default function App({ Component, pageProps }: AppProps) {
 }
 ```
 
-## Next.js Integration
+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/)
 
-To use the library with Next.js, you will need to dynamically import the `VeChainKit` provider in your `_app.tsx` file.
+This project uses:
 
-```typescript
-import dynamic from 'next/dynamic';
+-   `@privy-io/react-auth` for Privy connection type
+-   `@privy-io/cross-app-connect` for ecosystem cross app connection
 
-// Dynamic import is used here for several reasons:
-// 1. The VechainKit component uses browser-specific APIs that aren't available during server-side rendering
-// 2. Code splitting - this component will only be loaded when needed, reducing initial bundle size
-// 3. The 'ssr: false' option ensures this component is only rendered on the client side
-const VechainKitProvider = dynamic(
-    async () => (await import('@vechain/vechain-kit')).VechainKitProvider,
-    {
-        ssr: false,
-    },
-);
+You can import privy from the kit as
 
-export default function App({ Component, pageProps }: AppProps) {
-    return (
-        <VechainKitProvider>
-            <Component {...pageProps} />
-        </VechainKitProvider>
-    );
-}
+```typescript
+import { usePrivy } from '@vechain/vechain-kit';
+
+const { user } = usePrivy();
 ```
 
-# Usage Guide
+### Use the kit
+
+Once you setup the kit provider and created your fee delegation service you are good to go and you can allow your users to login.
 
-## Wallet Connection
+#### Wallet Button
 
-### Using the WalletButton Component
+You can use this component by importing it from the kit, it will handle for you the connection state and show a login button if the user is disconnected or the profile button when the user is connected.
 
 ```typescript
+'use client';
+
 import { WalletButton } from '@vechain/vechain-kit';
 
-<WalletButton />;
+export function Page() {
+    return <WalletButton />;
+}
 ```
 
-### Custom Connection Button
+#### Custom button
+
+Alternatively, you can create your own custom button and invoke the connect modal or account modal based on your needs.
 
 ```typescript
-import { useConnectModal } from '@vechain/vechain-kit';
+'use client';
 
-const { open } = useConnectModal();
+import {
+    useConnectModal,
+    useAccountModal,
+    useWallet,
+} from '@vechain/vechain-kit';
 
-<Button onClick={open}>Connect Wallet</Button>;
-```
+export function Page() {
+    const { connection } = useWallet();
 
-## Wallet Information
+    const {
+        open: openConnectModal,
+        close: closeConnectModal,
+        isOpen: isConnectModalOpen,
+    } = useConnectModal();
 
-```typescript
-import { useWallet } from '@vechain/vechain-kit';
+    const {
+        open: openAccountModal,
+        close: openAccountModal,
+        isOpen: isAccountModalOpen,
+    } = useAccountModal();
+
+    if (!connection.isConnected) {
+        return <button onClick={openConnectModal}> Connect </button>;
+    }
 
-const { account, connection } = useWallet();
+    return <button onClick={openAccountModal}> View Account </button>;
+}
 ```
 
-## Transaction Management
+# Usage Guide
 
-You can use the `useSendTransaction` hook to send transactions to the blockchain, all you will need is to build the clause and pass it to the hook.
+## Wallet Information
+
+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.
 
 ```typescript
-import { useSendTransaction } from '@vechain/vechain-kit';
+import { useWallet } from "@vechain/vechain-kit";
 
-const { sendTransaction } = useSendTransaction();
+function MyComponent = () => {
+    const {
+        account,
+        connectedWallet,
+        smartAccount,
+        dappKitWallet,
+        embeddedWallet,
+        crossAppWallet,
+        privyUser,
+        connection,
+        disconnect
+    } = useWallet();
+
+    return <></>
+}
 ```
 
-And you can mix it with the provided components to create a seamless experience for your users.
+## Transaction Management
+
+You need to use the `useSendTransaction` hook to send transactions to the blockchain, all you will need is to build the clause and pass it to the hook.
+
+This hook will take care of checking your connection type and handle the transaction submission between privy, cross-app and wallet connections.
+When implementing VeChain Kit it is mandatory to use this hook to send transaction.
 
 ```typescript
+'use client';
+
 import {
-    TransactionModal,
+    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 MyComponent = () => {
     const {
         sendTransaction,
         status,
@@ -196,7 +286,7 @@ const MyComponent = () => {
         error,
         progress,
     } = useSendTransaction({
-        signerAccountAddress: account?.address,
+        signerAccountAddress: account?.address ?? '',
     });
 
     const {
@@ -205,55 +295,51 @@ const MyComponent = () => {
         isOpen: isTransactionModalOpen,
     } = useTransactionModal();
 
-    // A dummy tx sending 0 b3tr tokens
-    const clauses = useMemo(() => {
-        if (!connectedWallet.address) return [];
-
-        const clausesArray: any[] = [];
-        const abi = new Interface(b3trAbi);
-        clausesArray.push({
-            to: b3trMainnetAddress,
-            value: '0x0',
-            data: abi.encodeFunctionData('transfer', [
-                connectedWallet.address,
-                '0', // 1 B3TR (in wei)
-            ]),
-            comment: `This is a dummy transaction to test the transaction modal. Confirm to transfer ${0} B3TR to ${humanAddress(
-                connectedWallet.address,
-            )}`,
-            abi: abi.getFunction('transfer'),
-        });
-
-        return clausesArray;
-    }, [connectedWallet.address]);
-
-    const handleTransactionWithModal = useCallback(async () => {
+    // This is the function triggering the transaction and opening the modal
+    const handleTransaction = useCallback(async () => {
         openTransactionModal();
         await sendTransaction(clauses);
-    }, [sendTransaction, clauses]);
+    }, [sendTransaction, clauses, openTransactionModal]);
 
     return (
-        <Button
-            onClick={handleTransactionWithModal}
-            isLoading={isTransactionPending}
-            isDisabled={isTransactionPending}
-        >
-            Tx with modal
-        </Button>
+        <>
+            <button
+                onClick={handleTransactionWithModal}
+                isLoading={isTransactionPending}
+                isDisabled={isTransactionPending}
+            >
+                Send B3TR
+            </button>
+
+            <TransactionModal
+                isOpen={isTransactionModalOpen}
+                onClose={closeTransactionModal}
+                status={status}
+                progress={progress}
+                txId={txReceipt?.meta.txID}
+                errorDescription={error?.reason ?? 'Unknown error'}
+                showSocialButtons={true}
+                showExplorerButton={true}
+                onTryAgain={handleTransactionWithModal}
+                showTryAgainButton={true}
+            />
+        </>
     );
-};
+}
 ```
 
 You can also use `useSignMessage` and `useSignTypedData` hooks to sign messages and typed data.
 
 ## Blockchain Data Reading
 
-The kit provides tons of hooks to read data from the blockchain (VeBetterDAO, veDelegate, vetDomains, balances, etc.)
+The kit provides hooks for developers to interact with smart contracts like VeBetterDAO, VePassport, veDelegate, and price oracles. These hooks work with react-query, improving query capabilities by caching responses and offering real-time states like isLoading and isError. This helps developers manage and update user interfaces effectively, ensuring a responsive experience.
 
 For example you can use `useGetB3trBalance` to get the balance of the user's wallet.
 
 ```typescript
 import { useGetB3trBalance } from '@vechain/vechain-kit';
 
-const { data: balance, isLoading, isError } = useGetB3trBalance();
+const { data: balance, isLoading, isError } = useGetB3trBalance('0x.....');
+
+console.log(balance.formatted, balance.original, balance.scaled);
 ```

package/dist/{Constants-Q8PYUyoh.d.cts → Constants-Cu1LVhH4.d.cts}

@@ -6,6 +6,7 @@ type Wallet = {
 type SmartAccount = Wallet & {
     isDeployed: boolean;
     isActive: boolean;
+    version: string | null;
 };
 type ConnectionSource = {
     type: 'privy' | 'wallet' | 'privy-cross-app';

package/dist/{Constants-Q8PYUyoh.d.ts → Constants-Cu1LVhH4.d.ts}

@@ -6,6 +6,7 @@ type Wallet = {
 type SmartAccount = Wallet & {
     isDeployed: boolean;
     isActive: boolean;
+    version: string | null;
 };
 type ConnectionSource = {
     type: 'privy' | 'wallet' | 'privy-cross-app';