Conduit UCPI Web3 SDK

A lightweight JavaScript/TypeScript SDK that provides a simple interface for web3 operations on the Conduit UCPI Avalanche subnet. The SDK handles Web3Auth authentication, service communication, and transaction signing while abstracting all blockchain complexity from the client.

Features

• 🔐 Web3Auth Integration - Seamless wallet authentication
• 📝 Contract Operations - Deploy and interact with smart contracts
• 💰 On-Ramp Services - Fiat to crypto conversion
• 👛 Wallet Management - Balance queries and transaction history
• ⚡ One-Click Deployment - Complete contract deployment with funding
• 🎣 React Hooks - Ready-to-use React components
• 🛡️ Type Safety - Full TypeScript support
• 🔄 Error Handling - Comprehensive error management

Installation

npm install @conduit-ucpi/web3-sdk
# or
yarn add @conduit-ucpi/web3-sdk

Quick Start

Basic Usage

import { ConduitSDK } from '@conduit-ucpi/web3-sdk';

const sdk = new ConduitSDK({
  apiKey: 'sk_live_your_api_key_here',
  environment: 'production',
  web3authClientId: 'BH_your_web3auth_client_id'
});

// Connect wallet
const address = await sdk.connect();
console.log('Connected:', address);

// Deploy an ERC20 token
const token = await sdk.deployContract('erc20', {
  name: 'My Token',
  symbol: 'MTK',
  decimals: 18,
  initialSupply: '1000000'
});
console.log('Token deployed at:', token.contractAddress);

One-Click Contract Deployment with Funding

// Complete flow with automatic funding
const result = await sdk.deployContractWithFunding('erc20', {
  name: 'My Business Token',
  symbol: 'MBT',
  decimals: 18,
  initialSupply: '1000000'
}, 50, { // $50 funding
  onrampProvider: 'moonpay',
  onStepComplete: (step, data) => {
    console.log(`✅ ${step}:`, data);
  },
  onStepError: (step, error) => {
    console.error(`❌ ${step}:`, error);
  }
});

if (result.success) {
  console.log('🎉 Contract deployed successfully!');
  console.log('Contract Address:', result.contractAddress);
  console.log('Transaction Hash:', result.transactionHash);
}

React Integration

import React from 'react';
import { useConduitSDK, useBalance, useAllBalances } from '@conduit-ucpi/web3-sdk';

function App() {
  const { sdk, isConnected, address, connect, disconnect } = useConduitSDK({
    apiKey: 'sk_live_your_api_key_here',
    environment: 'production',
    web3authClientId: 'BH_your_web3auth_client_id'
  });

  const { balance } = useBalance(sdk);
  const { balances } = useAllBalances(sdk);

  return (
    <div>
      {!isConnected ? (
        <button onClick={connect}>Connect Wallet</button>
      ) : (
        <div>
          <p>Connected: {address}</p>
          <p>Balance: {balance?.balanceFormatted} {balance?.symbol}</p>
          <button onClick={disconnect}>Disconnect</button>
        </div>
      )}
    </div>
  );
}

API Reference

Configuration

interface ConduitSDKConfig {
  apiKey: string;
  environment: 'production' | 'staging' | 'development';
  web3authClientId: string;
  apiBaseUrl?: string;
  timeout?: number;
  retryAttempts?: number;
  enableLogging?: boolean;
}

Authentication

// Connect wallet
const address: string = await sdk.connect();

// Disconnect wallet
await sdk.disconnect();

// Check connection status
const isConnected: boolean = sdk.isConnected();

// Get user address
const address: string | null = sdk.getAddress();

// Get session token
const token: string | null = sdk.getSessionToken();

Contract Operations

// Deploy contract
const result: DeploymentResult = await sdk.deployContract(type, params);

// Call contract function
const result: TransactionResult = await sdk.callContract(
  address,
  functionName,
  args,
  options
);

// Read from contract
const data: any = await sdk.readContract(
  address,
  functionName,
  args,
  abi
);

On-Ramp Operations

// Buy USDC with fiat
const result: OnRampResult = await sdk.buyUSDC(amount, options);

// Get available providers
const providers: OnRampProvider[] = await sdk.getOnRampProviders();

// Get quote
const quote: OnRampQuote = await sdk.getOnRampQuote(amount, currency, provider);

// Check status
const status: OnRampStatus = await sdk.getOnRampStatus(sessionId);

// Get history
const history: OnRampTransaction[] = await sdk.getOnRampHistory();

Wallet Operations

// Get token balance
const balance: TokenBalance = await sdk.getBalance(tokenAddress);

// Get all balances
const summary: WalletSummary = await sdk.getAllBalances();

// Get transaction history
const history: TransactionHistory = await sdk.getTransactionHistory(options);

// Get transaction status
const status: TransactionStatus = await sdk.getTransactionStatus(txHash);

Utility Operations

// Get nonce
const nonce: number = await sdk.getNonce();

// Estimate gas
const gasEstimate: string = await sdk.estimateGas(to, data, value);

// Get token info
const info: TokenInfo = await sdk.getTokenInfo(tokenAddress);

// Detect tokens
const tokens: TokenInfo[] = await sdk.detectTokens();

Contract Types

ERC20 Token

const erc20Params: ERC20Params = {
  name: 'My Token',
  symbol: 'MTK',
  decimals: 18,
  initialSupply: '1000000000000000000000000' // 1M tokens
};

ERC721 NFT

const erc721Params: ERC721Params = {
  name: 'My NFT Collection',
  symbol: 'MNC',
  baseTokenURI: 'https://api.example.com/metadata/'
};

ERC1155 Multi-Token

const erc1155Params: ERC1155Params = {
  name: 'My Multi-Token Collection',
  symbol: 'MMC',
  baseTokenURI: 'https://api.example.com/metadata/'
};

React Hooks

useConduitSDK

const { sdk, isConnected, address, connect, disconnect } = useConduitSDK(config);

useBalance

const { balance, isLoading, error, refetch } = useBalance(sdk, tokenAddress);

useAllBalances

const { balances, isLoading, error, refetch } = useAllBalances(sdk);

useTransactionHistory

const { history, isLoading, error, loadMore, hasMore } = useTransactionHistory(sdk, options);

useOnRamp

const { buyUSDC, getProviders, getQuote, isLoading, error } = useOnRamp(sdk);

Error Handling

The SDK provides comprehensive error handling with specific error types:

import { 
  ConduitSDKError, 
  AuthenticationError, 
  NetworkError, 
  ContractError 
} from '@conduit-ucpi/web3-sdk';

try {
  await sdk.deployContract('erc20', params);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof ContractError) {
    console.error('Contract operation failed:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

Utility Functions

Validation

import { validateAddress, validateAmount } from '@conduit-ucpi/web3-sdk';

const isValidAddress = validateAddress('0x1234...');
const isValidAmount = validateAmount('100.50');

Formatting

import { formatAddress, formatBalance, formatUSDValue } from '@conduit-ucpi/web3-sdk';

const shortAddress = formatAddress('0x1234567890abcdef...'); // 0x1234...cdef
const formattedBalance = formatBalance('1000000000000000000', 18); // 1.0
const usdValue = formatUSDValue('1234.56'); // $1,234.56

Development

Building

npm run build

Development Mode

npm run dev

Testing

npm test

Linting

npm run lint

License

MIT License - see LICENSE file for details.

Support

For support and questions, please contact:

• Email: [email protected]
• Documentation: https://docs.conduit-ucpi.com
• GitHub Issues: https://github.com/conduit-ucpi/web3-sdk/issues