@zentwallet/sdk

ZentWallet SDK - Connect to ZentChain wallet for balances, transactions, and signing.

Installation

npm install @zentwallet/sdk

Quick Start

1. Wrap your app with WalletProvider

import { WalletProvider } from '@zentwallet/sdk';

function App() {
  return (
    <WalletProvider>
      <YourApp />
    </WalletProvider>
  );
}

2. Use the wallet hook

import { useWallet } from '@zentwallet/sdk';

function YourComponent() {
  const { 
    walletAddress,
    walletBalance,
    isConnected,
    connectWallet,
    createWallet,
    sendTransaction,
    refreshBalance
  } = useWallet();

  if (!isConnected) {
    return <button onClick={() => createWallet()}>Create Wallet</button>;
  }

  return (
    <div>
      <p>Address: {walletAddress}</p>
      <p>Balance: {walletBalance} ZENT</p>
      <button onClick={refreshBalance}>Refresh Balance</button>
    </div>
  );
}

Configuration

You can configure the SDK with custom network settings:

<WalletProvider
  config={{
    defaultNetwork: 'testnet', // or 'mainnet'
    mainnetRpcUrl: 'https://rpc.zentchain.com',
    testnetRpcUrl: 'https://rpc-testnet.zentchain.com',
    mainnetExplorerUrl: 'https://explorer.zentchain.com',
    testnetExplorerUrl: 'https://explorer-testnet.zentchain.com',
    transactionApiUrl: '/api/transactions' // Optional custom API
  }}
>
  <YourApp />
</WalletProvider>

API Reference

useWallet Hook

Returns the following:

State

• walletAddress: string | null - Current wallet address
• walletBalance: string - Formatted wallet balance in ZENT
• network: 'testnet' | 'mainnet' - Current network
• isConnected: boolean - Whether wallet is connected
• isLoading: boolean - Loading state
• error: string | null - Error message if any

Actions

• connectWallet(privateKey: string) - Connect to existing wallet
• createWallet() - Create new wallet (returns { address, mnemonic })
• disconnect() - Disconnect wallet
• refreshBalance() - Refresh wallet balance
• sendTransaction(params) - Send transaction
• signTransaction(params) - Sign transaction without sending
• switchNetwork(network) - Switch between testnet/mainnet
• getTransactionHistory(page, limit) - Get transaction history
• getWeb3Manager() - Get underlying Web3Manager instance

Transaction Parameters

interface SendTransactionParams {
  to: string;        // Recipient address
  amount: string;    // Amount in ZENT (as string)
  notes?: string;    // Optional transaction notes
}

Examples

Create a new wallet

const { createWallet } = useWallet();

const handleCreateWallet = async () => {
  try {
    const { address, mnemonic } = await createWallet();
    console.log('Wallet created:', address);
    console.log('Mnemonic:', mnemonic);
    // IMPORTANT: Save mnemonic securely!
  } catch (error) {
    console.error('Failed to create wallet:', error);
  }
};

Connect to existing wallet

const { connectWallet } = useWallet();

const handleConnect = async (privateKey: string) => {
  try {
    await connectWallet(privateKey);
    console.log('Wallet connected');
  } catch (error) {
    console.error('Failed to connect:', error);
  }
};

Send transaction

const { sendTransaction, walletAddress } = useWallet();

const handleSend = async () => {
  try {
    const txHash = await sendTransaction({
      to: '0x...',
      amount: '10',
      notes: 'Payment for services'
    });
    console.log('Transaction sent:', txHash);
  } catch (error) {
    console.error('Transaction failed:', error);
  }
};

Get transaction history

const { getTransactionHistory } = useWallet();

const loadTransactions = async () => {
  const transactions = await getTransactionHistory(1, 20);
  console.log('Transactions:', transactions);
};

Switch network

const { switchNetwork } = useWallet();

const handleSwitchNetwork = async () => {
  await switchNetwork('mainnet'); // or 'testnet'
};

Storage

The SDK automatically stores wallet data securely in localStorage with encryption. The wallet persists across page reloads.

To clear stored wallet:

const { disconnect } = useWallet();
disconnect(); // This clears stored wallet

Security Notes

• Private keys are encrypted before storage
• Never expose private keys in components
• Always use the SDK's methods for signing transactions
• Store mnemonics securely (not in localStorage)

Advanced Usage

Direct Web3Manager access

import { Web3Manager } from '@zentwallet/sdk';

const manager = new Web3Manager({
  defaultNetwork: 'testnet'
});

const balance = await manager.getWalletBalance('0x...');

WalletManager instance

import { WalletManager } from '@zentwallet/sdk';

const walletManager = new WalletManager({
  defaultNetwork: 'testnet'
});

await walletManager.connectWallet(privateKey);

TypeScript Support

Full TypeScript support included. All types are exported:

import type { 
  Wallet, 
  WalletTransaction, 
  NetworkType,
  SDKConfig 
} from '@zentwallet/sdk';

License

MIT