@tippingchain/sdk

TypeScript SDK for TippingChain v2.6 - a unified multi-chain tipping platform with integrated Relay.link bridging, creator registry, and viewer rewards. Enable users to tip content creators using creator IDs from 9 source chains with automatic USDC payouts on ApeChain.

Version 2.6 Updates

• ✨ Updated Testnet Support: Complete migration from deprecated Holesky/Curtis to active Arbitrum Sepolia (421614) and Base Sepolia (84532)
• 🌐 Enhanced Chain Definitions: Updated all chain configurations with current testnet networks and proper RPC endpoints
• 🔧 Improved Contract Integration: Enhanced thirdweb SDK integration with full function signature resolution for contract methods
• 📊 Updated Fee Calculations: Accurate 5% platform fee for tips, 1% for viewer rewards with tier-based creator splits
• 🧪 Production-Ready Testnet: Full end-to-end cross-chain testing flow with real Relay.link bridging Arbitrum Sepolia → Base Sepolia
• 📦 Package Alignment: Compatible with @tippingchain/contracts-interface v1.6.0 and ui-react v2.6.0
• 🔗 Enhanced Relay Service: Improved ApeChainRelayService with testnet API support and better error handling
• 💰 Updated Token Support: Current testnet token addresses and configurations for USDC on supported chains
• 🔒 Improved Type Safety: Better TypeScript integration with thirdweb v5 and enhanced method resolution
• 🎯 Enhanced Error Handling: Better error messages and debugging support for testnet development

Features

• 🌐 Multi-chain support: 9 source chains (ETH, MATIC, OP, BSC, Abstract, AVAX, Base, Arbitrum, Taiko) → ApeChain
• 🔄 Integrated bridging: Built-in Relay.link functionality in smart contracts (no SDK relay needed)
• 💰 Dual fee structure: 5% for creator tips, 1% for viewer rewards
• 💵 USDC Payouts: All tips and rewards converted to stable USDC on ApeChain
• 🆔 Creator Registry: Simple creator ID system with wallet recovery
• 🎁 Viewer Rewards: Creators can reward audience members with batch support
• 🔑 Thirdweb Integration: Full support for thirdweb account IDs and smart accounts
• 🚀 Easy integration: Simple TypeScript SDK with React support
• 🔒 Type-safe: Full TypeScript support with comprehensive types

Installation

npm install @tippingchain/sdk thirdweb

Quick Start

1. Initialize the SDK

import { ApeChainTippingSDK, SUPPORTED_CHAINS, SUPPORTED_TESTNETS } from '@tippingchain/sdk';

// Production/Mainnet
const sdk = new ApeChainTippingSDK({
  clientId: 'your-thirdweb-client-id',
  environment: 'production',
  // Contract addresses are automatically loaded from @tippingchain/contracts-interface
  // Only specify streamingPlatformAddresses if using custom deployments
});

// Testnet
const testnetSdk = new ApeChainTippingSDK({
  clientId: 'your-thirdweb-client-id',
  environment: 'development',
  useTestnet: true // Uses Arbitrum Sepolia (421614) and Base Sepolia (84532) for cross-chain testing
});

2. Add a Creator (Platform Admin or Designated Admin)

// Register a new creator on all chains and get their ID (requires admin permissions)
const creatorId = await sdk.addCreator({
  creatorWallet: '0x1234567890123456789012345678901234567890',
  tier: 0, // TIER_1 (60/40 split)
  // chainId is optional - if not specified, registers on all deployed chains
});

console.log(`Creator registered with ID: ${creatorId}`);

// Register with thirdweb account ID
const creatorId = await sdk.addCreator({
  creatorWallet: '0x1234567890123456789012345678901234567890',
  thirdwebId: 'user_abcdef123456',
  tier: 0
});

// Or register on a specific chain only
const creatorId = await sdk.addCreator({
  creatorWallet: '0x1234567890123456789012345678901234567890',
  tier: 0,
  chainId: SUPPORTED_CHAINS.POLYGON // Only register on Polygon
});

3. Send a Tip

// Send native token tip using creator ID (testnet example)
const result = await sdk.sendTip({
  sourceChainId: 421614, // Arbitrum Sepolia testnet
  creatorId: 1, // Use creator ID instead of wallet address
  token: 'native',
  amount: '10000000000000000', // 0.01 ETH in wei (testnet amount)
});

if (result.success) {
  console.log(`🎉 Tip sent! TX: ${result.sourceTransactionHash}`);
  console.log(`   Creator ID: ${result.creatorId}`);
  console.log(`   Estimated USDC: ${result.estimatedUsdcAmount}`);
}

4. Creator Management

// Get creator info by ID (testnet example)
const creator = await sdk.getCreator(1, 421614); // Arbitrum Sepolia
console.log(`Creator: ${creator.wallet}, Tips: ${creator.totalTips}`);

// Find creator by wallet address
const creator2 = await sdk.getCreatorByWallet('0x479945d7931baC3343967bD0f839f8691E54a66e', 421614);

// Update creator wallet (for lost wallet recovery) - requires admin permissions
await sdk.updateCreatorWallet(1, '0xNewWalletAddress', 421614);

// Admin management functions (contract owner only) - testnet examples
await sdk.grantAdmin('0x29aE0362FcF55cc646fD83B6E0DeB433FF7e019b', 421614); // Testnet admin
await sdk.revokeAdmin('0xAdminWalletAddress', 421614);
const isAdmin = await sdk.isAdmin('0x29aE0362FcF55cc646fD83B6E0DeB433FF7e019b', 421614);

// Get platform statistics
const stats = await sdk.getPlatformStats(421614); // Arbitrum Sepolia
console.log(`Active Creators: ${stats.activeCreators}`);
console.log(`Total Tips: ${stats.totalTips}`);

// Get top creators leaderboard
const topCreators = await sdk.getTopCreators(10, 421614);

5. Viewer Rewards

// Send a reward to a viewer (creators only) - testnet example
const rewardResult = await sdk.rewardViewer({
  viewerAddress: '0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', // Test tipper wallet
  amount: '10000000000000000', // 0.01 ETH in wei (testnet amount)
  reason: 'Great question during the stream!',
  token: 'native',
  chainId: 421614 // Arbitrum Sepolia testnet
});

if (rewardResult.success) {
  console.log(`🎁 Reward sent! TX: ${rewardResult.transactionHash}`);
  console.log(`   Viewer receives: ${rewardResult.viewerAmount}`);
  console.log(`   Platform fee (1%): ${rewardResult.platformFee}`);
  console.log(`   Estimated USDC on ApeChain: ${rewardResult.estimatedUsdcAmount}`);
}

// Reward using viewer ID (for registered viewers)
const rewardByIdResult = await sdk.rewardViewer({
  viewerId: 123, // Use viewer ID instead of address
  amount: '100000000000000000',
  reason: 'Active participant!'
});

// Reward using thirdweb ID
const rewardByThirdwebId = await sdk.rewardViewer({
  thirdwebId: 'user_xyz789', // Thirdweb account ID
  amount: '100000000000000000',
  reason: 'Great contribution!'
});

// Batch reward multiple viewers (gas efficient) - testnet example
const batchResult = await sdk.batchRewardViewers({
  viewers: [
    { address: '0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', amount: '5000000000000000', reason: 'Active participant' },
    { address: '0x29aE0362FcF55cc646fD83B6E0DeB433FF7e019b', amount: '10000000000000000', reason: 'Best question' },
    { address: '0x479945d7931baC3343967bD0f839f8691E54a66e', amount: '7500000000000000', reason: 'Helpful feedback' }
  ],
  chainId: 421614 // Arbitrum Sepolia testnet
});

// Check viewer reward stats
const stats = await sdk.getViewerRewardStats('0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', 421614);
console.log(`Total rewards given: ${stats.totalRewardsGiven}`);
console.log(`Total rewards received: ${stats.totalRewardsReceived}`);
console.log(`Number of rewards sent: ${stats.rewardCount}`);

// Check if viewer rewards are enabled
const enabled = await sdk.areViewerRewardsEnabled(421614); // Arbitrum Sepolia
console.log(`Viewer rewards enabled: ${enabled}`);

// Enable or disable viewer rewards (admin only)
await sdk.setViewerRewardsEnabled(true, 421614);

// Check viewer's USDC balance on Base Sepolia (testnet destination)
const usdcBalance = await sdk.getViewerUsdcBalanceOnApeChain('0x65dF34504D2a5D96f4478544D5279B12b3fbEA87');
console.log(`USDC Balance on Base Sepolia: ${(parseFloat(usdcBalance) / 1e6).toFixed(2)} USDC`);

6. Token Balance and Approval Methods

// Get native token balance for a wallet (testnet example)
const balance = await sdk.getNativeBalance('0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', 421614);
console.log(`Balance: ${(parseFloat(balance) / 1e18).toFixed(4)} ETH`);

// Get ERC20 token balance (testnet USDC)
const tokenBalance = await sdk.getTokenBalance(
  '0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', // test wallet address
  '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', // USDC on Arbitrum Sepolia
  421614 // Arbitrum Sepolia
);
console.log(`USDC Balance: ${(parseFloat(tokenBalance) / 1e6).toFixed(2)} USDC`);

// Get multiple token balances at once
const balances = await sdk.getMultipleTokenBalances(
  '0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', 
  ['native', '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d'], // Native + USDC on Arbitrum Sepolia
  421614
);
console.log(`Balances:`, balances);

// Check if token approval is needed (testnet example)
const needsApproval = await sdk.needsApproval(
  '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', // USDC on Arbitrum Sepolia
  '0x65dF34504D2a5D96f4478544D5279B12b3fbEA87',
  '0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8', // TippingChain contract
  '1000000', // 1 USDC in smallest units
  421614 // Arbitrum Sepolia
);

// Approve token spending
const approval = await sdk.approveToken(
  '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', // USDC on Arbitrum Sepolia
  '0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8', // TippingChain contract
  '1000000', // 1 USDC
  421614
);

// Approve unlimited token spending
const maxApproval = await sdk.approveTokenMax(
  '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', // USDC on Arbitrum Sepolia
  '0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8', // TippingChain contract
  421614
);

7. Advanced Admin and Relay Management (NEW!)

// Add an authorized relayer for cross-chain operations (admin only) - testnet example
await sdk.addAuthorizedRelayer('0x29aE0362FcF55cc646fD83B6E0DeB433FF7e019b', 421614);

// Remove an authorized relayer (admin only)
await sdk.removeAuthorizedRelayer('0xRelayerAddress', 421614);

// Manually relay pending ETH to Base Sepolia (admin only)
await sdk.manualRelayETH(421614); // Arbitrum Sepolia

// Manually relay pending token to Base Sepolia (admin only)
await sdk.manualRelayToken('0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', 421614); // USDC

// Set auto-relay mode for cross-chain operations (admin only)
await sdk.setAutoRelay(true, 421614);

8. Contract State Management (NEW!)

// Pause contract operations (admin only) - testnet example
await sdk.pause(421614); // Arbitrum Sepolia

// Unpause contract operations (admin only)
await sdk.unpause(421614);

// Perform an emergency withdrawal of funds (admin only)
await sdk.emergencyWithdraw(421614);

9. Advanced Stats and Queries (NEW!)

// Get Base Sepolia-specific statistics (testnet destination)
const destStats = await sdk.getApeChainStats(84532); // Base Sepolia
console.log(`Total USDC on Base Sepolia: ${destStats.totalUsdc}`);
console.log(`Total from Chain: ${destStats.totalFromChain}`);

// Get all active creators with pagination (testnet example)
const activeCreators = await sdk.getAllActiveCreators(0, 10, 421614); // Arbitrum Sepolia
console.log(`Total Active Creators: ${activeCreators.totalActive}`);
console.log(`Creator IDs: ${activeCreators.creatorIds}`);
console.log(`Wallets: ${activeCreators.wallets}`);
console.log(`Tip Amounts: ${activeCreators.tipAmounts}`);

// Get information for multiple creators by IDs
const creatorsInfo = await sdk.getCreatorsByIds([1], 421614); // Creator #1 on testnet
console.log(`Tip Amounts: ${creatorsInfo.tipAmounts}`);
console.log(`Wallets: ${creatorsInfo.wallets}`);
console.log(`Active Status: ${creatorsInfo.activeStatus}`);

Supported Chains

Mainnet Chains

| Chain | Chain ID | Native Token | Type | |-------|----------|--------------|------| | Ethereum | 1 | ETH | Source | | Polygon | 137 | MATIC | Source | | Optimism | 10 | ETH | Source | | BSC | 56 | BNB | Source | | Abstract | 2741 | ETH | Source | | Avalanche | 43114 | AVAX | Source | | Base | 8453 | ETH | Source | | Arbitrum | 42161 | ETH | Source | | Taiko | 167000 | ETH | Source | | ApeChain | 33139 | APE | Destination |

Testnet Chains

Active Testnet Configuration:

| Chain | Chain ID | Native Token | Type | Contract Address | |-------|----------|--------------|------|-----------------| | Arbitrum Sepolia | 421614 | ETH | Source | 0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8 | | Base Sepolia | 84532 | ETH | Destination | 0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8 | | Polygon Amoy | 80002 | MATIC | Source (additional) | Available |

Testnet Network Details:

Arbitrum Sepolia:

• RPC: https://sepolia-rollup.arbitrum.io/rpc
• Explorer: https://sepolia.arbiscan.io
• Faucet: https://faucet.quicknode.com/arbitrum/sepolia
• USDC: 0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d

Base Sepolia:

• RPC: https://sepolia.base.org
• Explorer: https://sepolia.basescan.org
• Faucet: https://faucet.quicknode.com/base/sepolia
• USDC: 0x036CbD53842c5426634e7929541eC2318f3dCF7e

Note: Current testnet setup uses Arbitrum Sepolia → Base Sepolia for end-to-end cross-chain testing with real Relay.link bridging.

Fee Structure

Creator Tips

• Platform Fee: 5% to TippingChain Treasury
• Remaining 95% split based on creator's membership tier:
  • Tier 1: 60/40 (creator/business)
  • Tier 2: 70/30 (creator/business)
  • Tier 3: 80/20 (creator/business)
  • Tier 4: 90/10 (creator/business)

Viewer Rewards

• Platform Fee: 1% to TippingChain Treasury
• Viewer receives: 99% of reward amount
• All rewards are automatically converted to USDC and sent to ApeChain

Architecture Overview

Integrated Relay.link (v2.0+)

TippingChain v2.0+ features integrated Relay.link functionality directly in the TippingChain smart contracts:

• ✅ No separate bridge contracts needed (50% reduction in complexity)
• ✅ Automatic cross-chain bridging on every tip and viewer reward
• ✅ Direct USDC conversion and payout to ApeChain
• ✅ Simplified deployment - one contract per chain instead of two
• ✅ Gas efficient - single transaction handles tip + relay

How it works:

1. User sends tip/reward on source chain (e.g., Polygon)
2. Contract automatically deducts platform fee
3. Built-in relay integration bridges remaining tokens to ApeChain
4. Tokens are automatically converted to USDC on ApeChain
5. Recipients receive stable USDC payouts

Support

• Documentation: See the docs folder for detailed guides
• Examples: Check examples/ for usage patterns
• Contract Interface: @tippingchain/contracts-interface package

License

MIT License - see LICENSE file for details.