TokenOps SDK

A comprehensive TypeScript SDK for token operations on Ethereum and compatible blockchains. The TokenOps SDK provides a unified interface for vesting contracts, staking mechanisms, airdrops, token distribution, and analytics.

🚀 Features

Vesting Contracts (v3)

• Token Vesting Manager: Create and manage linear/cliff vesting schedules
• Native Token Vesting Manager: Handle ETH/native token vesting
• Voting-enabled Vesting: Governance capabilities for vested tokens
• Milestone-based Vesting: Vesting based on milestone completion
• Vault System: Secure token storage and management

Staking Contracts (v1)

• Standard Staking: Basic token staking with configurable rewards
• Unbonding Staking: Staking with unbonding periods
• Tiered Rewards: Multiple reward tiers based on stake amounts
• Whitelist Support: Merkle tree-based access control

Airdrop System (v2)

• Merkle Airdrops: Gas-efficient token distributions
• ERC20 & Native Token Support: Distribute any token type
• Claim and Stake: Direct staking during airdrop claims
• Time-based Windows: Configurable claim periods

Token Distribution (Disperse v2)

• Bulk Transfers: Send tokens to multiple recipients efficiently
• Flexible Fee Models: Gas fees or token-based fees
• Batch Operations: Optimize gas usage for large distributions

Analytics API

• Vesting Insights: Track vesting progress and metrics
• Event Monitoring: Real-time contract event tracking
• Webhook Support: Automated notifications
• Supply Analytics: Token supply and distribution data

📦 Installation

npm install tokenops-sdk

🛠️ Prerequisites

• Node.js >= 18.0.0
• TypeScript >= 5.0.0
• Ethereum wallet/provider (MetaMask, WalletConnect, etc.)

🚀 Quick Start

Initialize the SDK

import { ViemProviderAdapter, TokenOpsApi } from '@tokenops/sdk';
import { createPublicClient, createWalletClient, http } from 'viem';
import { mainnet } from 'viem/chains';

// Setup blockchain provider
const publicClient = createPublicClient({
  chain: mainnet,
  transport: http('YOUR_RPC_URL')
});

const walletClient = createWalletClient({
  chain: mainnet,
  transport: http('YOUR_RPC_URL'),
  account: 'YOUR_ACCOUNT'
});

const provider = new ViemProviderAdapter(publicClient, walletClient);

// Initialize API client
const api = new TokenOpsApi('YOUR_API_KEY');

💡 Usage Examples

Token Vesting

import { TokenVestingManagerFactory, TokenVestingManager } from '@tokenops/sdk';

// Deploy a new vesting manager
const factory = new TokenVestingManagerFactory(FACTORY_ADDRESS, provider);
const result = await factory.newTokenVestingManager(
  tokenAddress,
  BigInt(1), // funding type: partial
  { account: YOUR_ACCOUNT, value: BigInt(0) }
);

// Create vesting schedule
const manager = new TokenVestingManager(
  result.tokenVestingManager,
  tokenAddress,
  provider
);

const vestingResult = await manager.createVesting(
  recipientAddress,
  BigInt(startTimestamp),
  BigInt(endTimestamp),
  BigInt(0), // timelock
  BigInt(0), // initial unlock
  BigInt(cliffTimestamp),
  BigInt(cliffAmount),
  BigInt(releaseInterval),
  BigInt(linearVestAmount),
  true, // is revocable
  { account: YOUR_ACCOUNT, amount: BigInt(totalAmount) }
);

Staking

import { StakingFactory, Staking } from '@tokenops/sdk';

// Deploy staking contract
const stakingFactory = new StakingFactory(FACTORY_ADDRESS, provider);
const stakingResult = await stakingFactory.newStaking(
  merkleRoot,
  0, // whitelist status
  BigInt(poolMaxCap),
  stakingTokenAddress,
  BigInt(timeUnit),
  BigInt(rewardNumerator),
  BigInt(rewardDenominator),
  BigInt(tierUpperBound),
  BigInt(tierLowerBound),
  BigInt(startDate),
  BigInt(endDate),
  BigInt(fee)
);

// Stake tokens
const staking = new Staking(stakingResult.stakingContract, stakingTokenAddress, provider);
await staking.stake(BigInt(amount), merkleProof, { account: YOUR_ACCOUNT });

Airdrops

import { MerkleDistributorFactory, MerkleDistributorERC20 } from '@tokenops/sdk';

// Deploy airdrop contract
const airdropFactory = new MerkleDistributorFactory(FACTORY_ADDRESS, provider);
const airdropResult = await airdropFactory.newMerkleDistributor(
  tokenAddress,
  merkleRoot,
  startTime,
  endTime,
  stakingAddress,
  rewardOwner,
  bonusPercentage,
  { account: YOUR_ACCOUNT, value: BigInt(0) }
);

// Claim airdrop
const distributor = new MerkleDistributorERC20(airdropResult.merkleDistributor, provider);
await distributor.claim(
  claimIndex,
  recipientAddress,
  BigInt(amount),
  merkleProof,
  { account: YOUR_ACCOUNT }
);

Token Distribution

import { DisperseFactory, DisperseTokenFee } from '@tokenops/sdk';

// Deploy disperse contract
const disperseFactory = new DisperseFactory(FACTORY_ADDRESS, provider);
const disperseResult = await disperseFactory.newDisperseTokenFee({ account: YOUR_ACCOUNT });

// Distribute tokens
const disperse = new DisperseTokenFee(disperseResult.disperse, provider);
await disperse.disperseToken(
  tokenAddress,
  [recipient1, recipient2, recipient3],
  [BigInt(amount1), BigInt(amount2), BigInt(amount3)],
  { account: YOUR_ACCOUNT }
);

Analytics API

// Get vesting contract information
const vestingInfo = await api.vesting(chainId, contractAddress);

// Get vesting grants
const grants = await api.vestingGrants(
  chainId,
  contractAddress,
  tokenAddress,
  recipientAddress
);

// Get vesting insights
const insights = await api.vestingInsights(
  chainId,
  contractAddress,
  tokenAddress
);

// Subscribe to events
await api.vestingSubscribe(
  chainId,
  contractAddress,
  ['VestingCreated', 'Claimed'],
  'https://your-webhook-url.com'
);

🏗️ Architecture

The SDK is organized into several modules:

src/
├── API/                    # REST API client
├── airdrop-v2/            # Airdrop contracts and utilities
├── disperse-v2/           # Token distribution contracts
├── provider/              # Blockchain provider adapters
├── staking-contracts-v1/  # Staking mechanisms
├── vesting-contracts-v3/  # Vesting contracts
└── utils/                 # Shared utilities

🔧 Provider Support

The SDK supports multiple blockchain libraries:

• Viem (recommended): Modern, type-safe Ethereum library
• Ethers.js: Popular Ethereum library with wide adoption

// Viem provider
import { ViemProviderAdapter } from '@tokenops/sdk';
const provider = new ViemProviderAdapter(publicClient, walletClient);

// Ethers provider
import { EthersProviderAdapter } from '@tokenops/sdk';
const provider = new EthersProviderAdapter(ethersProvider);

🧪 Testing

The SDK includes comprehensive tests for all functionality:

npm test

Test files are organized by module and include:

• Unit tests for individual contract methods
• Integration tests for complete workflows
• Error handling and edge case testing

🔑 API Authentication

To use the analytics API, you need an API key:

1. Visit TokenOps Platform
2. Create an account and generate an API key
3. Use the key when initializing the API client

📚 API Reference

Factory Contracts

All contract deployments use factory patterns for consistent, upgradeable deployments:

• TokenVestingManagerFactory
• StakingFactory
• MerkleDistributorFactory
• DisperseFactory

Contract Managers

Each contract type has a corresponding manager class:

• TokenVestingManager
• Staking / StakingWithUnbonding
• MerkleDistributorERC20 / MerkleDistributorNative
• DisperseTokenFee / DisperseGasFee

Events

All contracts emit events that are automatically parsed:

• VestingCreated, Claimed, VestingRevoked
• TokensStaked, TokensWithdrawn, RewardsClaimed
• Claimed (airdrops), Withdrawn
• Transaction receipts with parsed event logs

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Documentation
• TokenOps Platform
• API Documentation
• GitHub Repository

💬 Support

For support and questions:

• Create an issue on GitHub
• Join our Discord
• Email: [email protected]

Built with ❤️ by the TokenOps team