Examples

📚 Examples

Real-world examples and common use cases for validator0x.

---

🎯 Basic Validation

Single Address Validation

import { validateAddress } from 'validator0x';

const address = '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb';
const result = validateAddress(address, 'ethereum');

if (result.valid) {
  console.log('✓ Valid Ethereum address');
  console.log('Format:', result.details?.format);
  console.log('Network:', result.details?.network);
} else {
  console.error('✗ Invalid address:', result.error);
}

Multi-Chain Validation

import { validateAddress, BlockchainType } from 'validator0x';

const addresses: Record<BlockchainType, string> = {
  ethereum: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  polygon: '0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063',
  solana: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  bitcoin: 'bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq'
};

Object.entries(addresses).forEach(([chain, address]) => {
  const result = validateAddress(address, chain as BlockchainType);
  console.log(`${chain}: ${result.valid ? '✓' : '✗'}`);
});

---

🌐 Web3 dApp Integration

Wallet Connection Validator

import { validateAddress, detectBlockchain } from 'validator0x';

async function connectWallet(walletAddress: string) {
  // Detect possible blockchains
  const possibleChains = detectBlockchain(walletAddress);

  if (possibleChains.length === 0) {
    throw new Error('Invalid wallet address format');
  }

  // Validate against the first detected chain
  const result = validateAddress(walletAddress, possibleChains[0]);

  if (!result.valid) {
    throw new Error(`Invalid ${possibleChains[0]} address: ${result.error}`);
  }

  return {
    address: walletAddress,
    blockchain: result.blockchain,
    details: result.details
  };
}

// Usage
try {
  const wallet = await connectWallet('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');
  console.log('Connected wallet:', wallet);
} catch (error) {
  console.error('Connection failed:', error.message);
}

Send Transaction Form

import { validateAddress, formatAddress } from 'validator0x';

interface TransactionData {
  recipient: string;
  amount: number;
  blockchain: BlockchainType;
}

function validateTransaction(tx: TransactionData): boolean {
  const result = validateAddress(tx.recipient, tx.blockchain, { strict: true });

  if (!result.valid) {
    alert(`Invalid recipient address: ${result.error}`);
    return false;
  }

  if (tx.amount <= 0) {
    alert('Amount must be greater than 0');
    return false;
  }

  return true;
}

// Before sending
const transaction: TransactionData = {
  recipient: '0x742d35cc6634c0532925a3b844bc9e7595f0beb',
  amount: 0.5,
  blockchain: 'ethereum'
};

if (validateTransaction(transaction)) {
  // Format address before display
  const formattedAddress = formatAddress(
    transaction.recipient,
    transaction.blockchain,
    { checksum: true }
  );

  console.log(`Sending ${transaction.amount} ETH to ${formattedAddress}`);
  // Proceed with transaction...
}

---

⚛️ React Examples

Form with Real-time Validation

import { useState, useEffect } from 'react';
import { validateAddress, BlockchainType } from 'validator0x';

interface WalletFormProps {
  blockchain: BlockchainType;
  onSubmit: (address: string) => void;
}

function WalletForm({ blockchain, onSubmit }: WalletFormProps) {
  const [address, setAddress] = useState('');
  const [isValid, setIsValid] = useState(false);
  const [error, setError] = useState('');

  useEffect(() => {
    if (address.length === 0) {
      setError('');
      setIsValid(false);
      return;
    }

    const result = validateAddress(address, blockchain);
    setIsValid(result.valid);
    setError(result.valid ? '' : result.error || 'Invalid address');
  }, [address, blockchain]);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (isValid) {
      onSubmit(address);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={address}
        onChange={(e) => setAddress(e.target.value)}
        placeholder={`Enter ${blockchain} address`}
        className={isValid ? 'valid' : error ? 'invalid' : ''}
      />
      {error && <p className="error">{error}</p>}
      {isValid && <p className="success">✓ Valid address</p>}
      <button type="submit" disabled={!isValid}>
        Submit
      </button>
    </form>
  );
}

Custom Hook

import { useState, useCallback } from 'react';
import { validateAddress, BlockchainType, ValidationResult } from 'validator0x';

function useAddressValidator(blockchain: BlockchainType) {
  const [result, setResult] = useState<ValidationResult | null>(null);
  const [isValidating, setIsValidating] = useState(false);

  const validate = useCallback((address: string) => {
    setIsValidating(true);

    // Simulate async validation (could include API calls)
    setTimeout(() => {
      const validationResult = validateAddress(address, blockchain);
      setResult(validationResult);
      setIsValidating(false);
    }, 100);
  }, [blockchain]);

  const reset = useCallback(() => {
    setResult(null);
    setIsValidating(false);
  }, []);

  return {
    validate,
    reset,
    isValidating,
    isValid: result?.valid ?? false,
    error: result?.error,
    details: result?.details
  };
}

// Usage
function AddressChecker() {
  const [address, setAddress] = useState('');
  const { validate, isValid, error, isValidating } = useAddressValidator('ethereum');

  return (
    <div>
      <input
        value={address}
        onChange={(e) => {
          setAddress(e.target.value);
          validate(e.target.value);
        }}
      />
      {isValidating && <span>Validating...</span>}
      {isValid && <span>✓ Valid</span>}
      {error && <span>✗ {error}</span>}
    </div>
  );
}

---

🎨 Address Display Components

Shortened Address Display

import { formatAddress } from 'validator0x';

interface AddressDisplayProps {
  address: string;
  blockchain: BlockchainType;
  shorten?: boolean;
  copyable?: boolean;
}

function AddressDisplay({
  address,
  blockchain,
  shorten = false,
  copyable = true
}: AddressDisplayProps) {
  const displayAddress = shorten
    ? formatAddress(address, blockchain, { shorten: true, shortenLength: 6 })
    : formatAddress(address, blockchain, { checksum: true });

  const handleCopy = () => {
    navigator.clipboard.writeText(address);
    alert('Address copied!');
  };

  return (
    <div className="address-display">
      <code>{displayAddress}</code>
      {copyable && (
        <button onClick={handleCopy} title="Copy full address">
          📋
        </button>
      )}
    </div>
  );
}

// Usage
<AddressDisplay
  address="0x742d35cc6634c0532925a3b844bc9e7595f0beb"
  blockchain="ethereum"
  shorten={true}
  copyable={true}
/>

Multi-Chain Address Selector

import { useState } from 'react';
import { validateAddress, detectBlockchain, BlockchainType } from 'validator0x';

const BLOCKCHAINS: BlockchainType[] = ['ethereum', 'solana', 'bitcoin', 'polygon'];

function MultiChainAddressInput() {
  const [address, setAddress] = useState('');
  const [selectedChain, setSelectedChain] = useState<BlockchainType>('ethereum');
  const [detectedChains, setDetectedChains] = useState<BlockchainType[]>([]);

  const handleAddressChange = (value: string) => {
    setAddress(value);

    // Auto-detect possible chains
    const detected = detectBlockchain(value);
    setDetectedChains(detected);

    // Auto-select if only one chain detected
    if (detected.length === 1) {
      setSelectedChain(detected[0]);
    }
  };

  const validation = validateAddress(address, selectedChain);

  return (
    <div>
      <input
        value={address}
        onChange={(e) => handleAddressChange(e.target.value)}
        placeholder="Enter wallet address"
      />

      <select
        value={selectedChain}
        onChange={(e) => setSelectedChain(e.target.value as BlockchainType)}
      >
        {BLOCKCHAINS.map(chain => (
          <option
            key={chain}
            value={chain}
            disabled={detectedChains.length > 0 && !detectedChains.includes(chain)}
          >
            {chain} {detectedChains.includes(chain) ? '✓' : ''}
          </option>
        ))}
      </select>

      {address && (
        <div className={validation.valid ? 'valid' : 'invalid'}>
          {validation.valid ? '✓ Valid' : `✗ ${validation.error}`}
        </div>
      )}
    </div>
  );
}

---

🔧 Backend/API Examples

Express.js REST API

import express from 'express';
import { validateAddress, formatAddress, detectBlockchain } from 'validator0x';

const app = express();
app.use(express.json());

// Validate endpoint
app.post('/api/validate', (req, res) => {
  const { address, blockchain, strict = false } = req.body;

  if (!address || !blockchain) {
    return res.status(400).json({
      success: false,
      error: 'Address and blockchain are required'
    });
  }

  const result = validateAddress(address, blockchain, { strict });

  res.json({
    success: result.valid,
    data: result
  });
});

// Format endpoint
app.post('/api/format', (req, res) => {
  const { address, blockchain, shorten = false } = req.body;

  try {
    const formatted = formatAddress(address, blockchain, { shorten });
    res.json({ success: true, formatted });
  } catch (error) {
    res.status(400).json({ success: false, error: error.message });
  }
});

// Detect endpoint
app.post('/api/detect', (req, res) => {
  const { address } = req.body;

  const chains = detectBlockchain(address);
  res.json({ success: true, chains });
});

app.listen(3000, () => {
  console.log('API running on port 3000');
});

Next.js API Route

// pages/api/validate.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { validateAddress } from 'validator0x';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const { address, blockchain } = req.body;

  if (!address || !blockchain) {
    return res.status(400).json({
      error: 'Missing required fields: address, blockchain'
    });
  }

  const result = validateAddress(address, blockchain);

  return res.status(result.valid ? 200 : 400).json(result);
}

---

🧪 Testing Examples

Jest Unit Tests

import { validateAddress, formatAddress, detectBlockchain } from 'validator0x';

describe('validator0x', () => {
  describe('validateAddress', () => {
    it('should validate correct Ethereum address', () => {
      const result = validateAddress(
        '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
        'ethereum'
      );

      expect(result.valid).toBe(true);
      expect(result.blockchain).toBe('ethereum');
    });

    it('should reject invalid Ethereum address', () => {
      const result = validateAddress('invalid-address', 'ethereum');

      expect(result.valid).toBe(false);
      expect(result.error).toBeDefined();
    });

    it('should validate in strict mode', () => {
      const result = validateAddress(
        '0x742d35cc6634c0532925a3b844bc9e7595f0beb', // wrong checksum
        'ethereum',
        { strict: true }
      );

      expect(result.valid).toBe(false);
    });
  });

  describe('formatAddress', () => {
    it('should apply EIP-55 checksum', () => {
      const formatted = formatAddress(
        '0x742d35cc6634c0532925a3b844bc9e7595f0beb',
        'ethereum',
        { checksum: true }
      );

      expect(formatted).toBe('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');
    });

    it('should shorten address', () => {
      const shortened = formatAddress(
        '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
        'ethereum',
        { shorten: true }
      );

      expect(shortened).toMatch(/^0x\w{4}\.\.\.\w{4}$/);
    });
  });

  describe('detectBlockchain', () => {
    it('should detect Ethereum/Polygon addresses', () => {
      const chains = detectBlockchain('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');

      expect(chains).toContain('ethereum');
      expect(chains).toContain('polygon');
    });

    it('should detect Solana addresses', () => {
      const chains = detectBlockchain('DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK');

      expect(chains).toContain('solana');
    });
  });
});

---

💼 Production Use Cases

Whitelist Validator

import { validateAddress } from 'validator0x';

const WHITELISTED_ADDRESSES = [
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  '0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063'
];

function isWhitelisted(address: string): boolean {
  // First validate format
  const result = validateAddress(address, 'ethereum');
  if (!result.valid) return false;

  // Normalize both addresses for comparison
  const normalized = formatAddress(address, 'ethereum', { checksum: true });

  return WHITELISTED_ADDRESSES.some(
    whitelistedAddr => formatAddress(whitelistedAddr, 'ethereum', { checksum: true }) === normalized
  );
}

Airdrop Validator

import { validateAddress, ValidationError } from 'validator0x';
import { readFileSync } from 'fs';

interface AirdropEntry {
  address: string;
  amount: number;
}

function validateAirdropList(csvPath: string): {
  valid: AirdropEntry[];
  invalid: Array<{ address: string; error: string }>;
} {
  const content = readFileSync(csvPath, 'utf-8');
  const lines = content.split('
').slice(1); // Skip header

  const valid: AirdropEntry[] = [];
  const invalid: Array<{ address: string; error: string }> = [];

  lines.forEach(line => {
    const [address, amount] = line.split(',');
    const result = validateAddress(address.trim(), 'ethereum', { strict: true });

    if (result.valid) {
      valid.push({
        address: formatAddress(address.trim(), 'ethereum', { checksum: true }),
        amount: parseFloat(amount)
      });
    } else {
      invalid.push({
        address: address.trim(),
        error: result.error || 'Unknown error'
      });
    }
  });

  return { valid, invalid };
}

---

🔗 Related Pages

• Getting Started - Installation and setup
• API Reference - Complete API documentation
• FAQ - Common questions
• Contributing - How to contribute

Have a use case not covered here? Open an issue and share it!