Package Exports

@charliepank/conduit-ucpi-web3-sdk
@charliepank/conduit-ucpi-web3-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@charliepank/conduit-ucpi-web3-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: support@conduit-ucpi.com
Documentation: https://docs.conduit-ucpi.com
GitHub Issues: https://github.com/conduit-ucpi/web3-sdk/issues