@soulsolidity/zap-widgets

SoulZap SDK

A React SDK for integrating SoulZap functionality into your applications. This SDK provides a set of UI components and utilities to enable users to zap from one token to another across different chains.

Features

• DEX-like UI/UX: Interactive swapping interface
• Token Selection: Dynamically fetch supported tokens from the registry
• Customizable UI: Style components to match your branding
• Wallet Integration: Works with any wallet connection library
• Flexible Integration: Easy-to-use components for React applications
• TypeScript Support: Full type definitions for all components and utilities

Installation

npm install zap:sdk
# or
yarn add zap:sdk

Quick Start

import { ZapProvider, ZapWidget } from 'zap:sdk';
import { useAccount } from 'wagmi';

function App() {
  // Get wallet address from your preferred wallet library
  const { address } = useAccount();

  // Handle successful zap
  const handleSuccess = (result) => {
    console.log('Zap successful:', result);
  };

  // Handle zap error
  const handleError = (error) => {
      console.error('Zap failed:', error);
  };

  return (
    <ZapProvider defaultUserAddress={address}>
      <ZapWidget 
        onSuccess={handleSuccess}
        onError={handleError}
      />
    </ZapProvider>
  );
}

Components

ZapWidget

The main component that provides a complete UI for zapping tokens.

<ZapWidget 
  className="custom-class"
  theme="light" // 'light', 'dark', or 'auto'
  onSuccess={handleSuccess}
  onError={handleError}
/>

Props

• className: Custom CSS class for styling
• theme: UI theme ('light', 'dark', or 'auto')
• onSuccess: Callback for successful zap
• onError: Callback for zap errors

ZapProvider

Context provider that manages the state and functionality for the zap components.

<ZapProvider
  defaultChainId={56}
  defaultFromToken="0x0000000000000000000000000000000000000000"
  defaultUserAddress={walletAddress}
>
  {/* Your components */}
</ZapProvider>

Props

• defaultChainId: Default chain ID to use
• defaultFromToken: Default token address to use as the source token
• defaultUserAddress: User's wallet address from your wallet connection library

Individual Components

The SDK also exports individual components for custom integrations:

• TokenSelector: Component for selecting tokens
• AmountInput: Input field for token amounts
• ChainSelector: Component for selecting blockchain networks
• TransactionPreview: Component for previewing transactions

Wallet Integration

The SDK is designed to work with any wallet connection library. Simply pass the user's wallet address to the ZapProvider component:

// With wagmi/viem
import { useAccount } from 'wagmi';

function App() {
  const { address } = useAccount();
  
  return (
    <ZapProvider defaultUserAddress={address}>
      <ZapWidget />
    </ZapProvider>
  );
}

// With ethers.js
import { useState, useEffect } from 'react';
import { ethers } from 'ethers';

function App() {
  const [address, setAddress] = useState('');
  
  useEffect(() => {
    const connectWallet = async () => {
      if (window.ethereum) {
        const provider = new ethers.providers.Web3Provider(window.ethereum);
        const accounts = await provider.send('eth_requestAccounts', []);
        setAddress(accounts[0]);
      }
    };
    
    connectWallet();
  }, []);
  
  return (
    <ZapProvider defaultUserAddress={address}>
      <ZapWidget />
    </ZapProvider>
  );
}

API

Hooks

• useZap(): Hook to access the zap context and functionality

Utilities

• fetchRegistry(): Fetch the zap registry data
• transformRegistryToTokens(): Transform registry data into a list of tokens
• getSupportedChains(): Get supported chains from the registry
• getTokensByChain(): Get tokens for a specific chain
• makeZapRequest(): Make a zap API call
• formatAddress(): Format an address to a shortened form
• formatNumber(): Format a number to a readable string
• isValidAddress(): Validate if a string is a valid Ethereum address
• chainIdToName(): Format a chain ID to its network name

API Endpoint

The SDK interacts with the following API endpoint:

GET http://localhost:3001/zap?fromToken=<address>&fromAmount=<amount>&toToken=<address>&chain=<chainId>&user=<walletAddress>

Registry Data

The SDK fetches supported tokens from the registry at: https://raw.githubusercontent.com/SoulSolidity/registry/main/data/constants/zap.json

Customization

Styling

The SDK uses Tailwind CSS for styling. You can customize the appearance by:

1. Providing custom classes via the className prop
2. Setting the theme prop to 'light', 'dark', or 'auto'
3. Overriding the CSS variables in your application

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build the SDK
npm run build:sdk

License

MIT