Conduit UCPI SDK

TypeScript SDK for Conduit UCPI escrow contracts on EVM-compatible blockchains.

Features

• 🔒 Secure Escrow Contracts: Time-delayed escrow with dispute resolution
• 🏗️ Framework Agnostic: Works with any wallet provider implementation
• 🎯 Type Safe: Full TypeScript support with comprehensive interfaces
• 🔄 Consistent Data Handling: Single source of truth for currency/timestamp operations
• 🌐 EVM Compatible: Supports Avalanche and other EVM chains
• 🧪 Fully Tested: Comprehensive test suite with 100% critical path coverage

Installation

npm install @conduit-ucpi/sdk

Quick Start

import { EscrowSDK, WalletProvider } from '@conduit-ucpi/sdk';

// Initialize SDK
const sdk = new EscrowSDK({
  chainId: 43113, // Avalanche Fuji testnet
  rpcUrl: 'https://api.avax-test.network/ext/bc/C/rpc',
  usdcContractAddress: '0x5425890298aed601595a70AB815c96711a31Bc65',
  userServiceUrl: 'https://api.conduit-ucpi.com/user',
  chainServiceUrl: 'https://api.conduit-ucpi.com/chain',
  contractServiceUrl: 'https://api.conduit-ucpi.com/contracts'
});

// Connect wallet (implement WalletProvider for your wallet)
await sdk.connectWallet(yourWalletProvider);

// Check USDC balance
const balance = await sdk.getUSDCBalance();
console.log(`Balance: ${sdk.utils.formatUSDC(balance)}`);

// Create escrow contract via backend services
const contract = await sdk.services.contracts.createContract({
  sellerEmail: '[email protected]',
  buyerEmail: '[email protected]', 
  sellerAddress: '0x...',
  amount: '100.00', // Will be converted to microUSDC automatically
  description: 'Service delivery escrow',
  expiryTimestamp: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) // 7 days
});

Architecture

The SDK provides a unified interface for:

Core Services

• Web3Service: Blockchain interactions (signing, contract calls)
• WalletManager: Wallet provider abstraction
• Config: Network and service configuration

Backend Service Clients

• UserServiceClient: Authentication and user management
• ChainServiceClient: Transaction relay and gas management
• ContractServiceClient: Escrow contract lifecycle management

Utilities

• Validation: Address, amount, email validation
• Formatting: Currency, timestamp, and display formatting
• Constants: Network configurations and contract addresses

Wallet Integration

The SDK uses a wallet provider abstraction pattern:

interface WalletProvider {
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  getAddress(): Promise<string>;
  signTransaction(transaction: any): Promise<string>;
  // ... other wallet methods
}

// Implement for your specific wallet
class MyWalletProvider implements WalletProvider {
  // Implementation specific to your wallet
}

Currency Handling

The SDK maintains strict consistency for currency operations:

// All internal amounts are in microUSDC (1 USDC = 1,000,000 microUSDC)
const amount = sdk.utils.toMicroUSDC('1.50'); // 1500000
const display = sdk.utils.fromMicroUSDC(1500000); // 1.5
const formatted = sdk.utils.formatUSDC(1500000); // "1.5000 USDC"

Timestamp Handling

All timestamps are normalized to milliseconds internally:

// All internal timestamps are Unix milliseconds
const timestamp = sdk.utils.normalizeTimestamp(1700000000); // Converts seconds to ms
const formatted = sdk.utils.formatDateTimeWithTZ(timestamp); // "2023-11-14T22:13:20-05:00"

Service Integration

Authentication

// Login with Web3Auth token
const auth = await sdk.services.user.login({
  idToken: 'web3auth-token',
  walletAddress: await sdk.getWalletAddress()
});

Contract Management

// Get user's contracts
const contracts = await sdk.services.contracts.getUserContracts(
  userAddress, 
  'address'
);

// Query contracts with filters
const activeContracts = await sdk.services.contracts.getContracts({
  status: 'active',
  startDate: new Date('2024-01-01'),
  limit: 10
});

Blockchain Operations

// Submit USDC transfer
const transfer = await sdk.services.chain.submitUSDCTransfer({
  to: recipientAddress,
  amount: '10.00', // Automatically converted to microUSDC
  signedTransaction: signedTx
});

// Create escrow contract on-chain
const escrow = await sdk.services.chain.createEscrowContract({
  buyer: buyerAddress,
  seller: sellerAddress,
  amount: '100.00',
  expiryTimestamp: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
  description: 'Service delivery'
});

Error Handling

The SDK provides consistent error handling:

import { SDKError, SDKErrorCode } from '@conduit-ucpi/sdk';

try {
  await sdk.connectWallet(provider);
} catch (error) {
  if (error instanceof SDKError) {
    switch (error.code) {
      case SDKErrorCode.WALLET_NOT_CONNECTED:
        console.log('Please connect your wallet');
        break;
      case SDKErrorCode.INVALID_ADDRESS:
        console.log('Invalid wallet address');
        break;
      default:
        console.log(`SDK Error: ${error.message}`);
    }
  }
}

Configuration

Network Configuration

// Avalanche Mainnet
const mainnetConfig = {
  chainId: 43114,
  rpcUrl: 'https://api.avax.network/ext/bc/C/rpc',
  usdcContractAddress: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E'
};

// Avalanche Fuji Testnet  
const testnetConfig = {
  chainId: 43113,
  rpcUrl: 'https://api.avax-test.network/ext/bc/C/rpc', 
  usdcContractAddress: '0x5425890298aed601595a70AB815c96711a31Bc65'
};

Service URLs

const config = {
  // ... network config
  userServiceUrl: 'https://api.conduit-ucpi.com/user',
  chainServiceUrl: 'https://api.conduit-ucpi.com/chain', 
  contractServiceUrl: 'https://api.conduit-ucpi.com/contracts'
};

API Reference

EscrowSDK

Main SDK class providing unified access to all functionality.

Service Clients

• UserServiceClient - Authentication and user management
• ChainServiceClient - Blockchain operations and gas management
• ContractServiceClient - Escrow contract CRUD operations

Utilities

• validation - Address, amount, email validation functions
• formatting - Currency, timestamp, display formatting functions
• constants - Network configurations and known contract addresses

Contributing

1. Clone the repository
2. Install dependencies: npm install
3. Run tests: npm test
4. Build: npm run build

License

MIT

Support

• GitHub Issues: https://github.com/conduit-ucpi/sdk/issues
• Documentation: https://github.com/conduit-ucpi/sdk