{"id":30145135,"url":"https://github.com/walletconnect/spl-dropper","last_synced_at":"2025-08-11T08:09:31.491Z","repository":{"id":308188725,"uuid":"1031948582","full_name":"WalletConnect/spl-dropper","owner":"WalletConnect","description":"A high-performance, production-ready SPL token distribution tool for Solana. Handles massive airdrops with automatic retry, state persistence, and crash recovery.","archived":false,"fork":false,"pushed_at":"2025-08-04T15:34:59.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-04T19:18:05.720Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WalletConnect.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-04T15:14:56.000Z","updated_at":"2025-08-04T15:35:02.000Z","dependencies_parsed_at":"2025-08-04T19:22:56.650Z","dependency_job_id":"1108cc16-26b1-4bfa-93c2-edb1c5ce04d6","html_url":"https://github.com/WalletConnect/spl-dropper","commit_stats":null,"previous_names":["walletconnect/spl-dropper"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/WalletConnect/spl-dropper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WalletConnect%2Fspl-dropper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WalletConnect%2Fspl-dropper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WalletConnect%2Fspl-dropper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WalletConnect%2Fspl-dropper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WalletConnect","download_url":"https://codeload.github.com/WalletConnect/spl-dropper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WalletConnect%2Fspl-dropper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269850366,"owners_count":24485177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-11T08:09:29.492Z","updated_at":"2025-08-11T08:09:31.473Z","avatar_url":"https://github.com/WalletConnect.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SPL Token Dropper\n\nA high-performance, production-ready SPL token distribution tool for Solana. Handles massive airdrops with automatic retry, state persistence, and crash recovery.\n\n## How It Works\n\n```mermaid\ngraph LR\n    CSV[📄 CSV File] --\u003e TOOL[SPL Dropper]\n    TOOL --\u003e SOL[⛓️ Solana]\n    TOOL \u003c--\u003e STATE[💾 State File]\n    \n    style TOOL fill:#e3f2fd\n```\n\n**Key Features:**\n- Batches 10 transfers per transaction for efficiency\n- Saves progress automatically (resume anytime)\n- Retries failed transactions automatically\n- Handles token account creation if needed\n\n## Features\n\n- 🚀 **High Performance**: Batch processing with configurable rate limiting\n- 💾 **State Persistence**: Automatic resume from interruptions\n- 🔄 **Smart Retries**: Handles expired transactions automatically\n- 📊 **Progress Tracking**: Real-time distribution progress with clear recipient ranges\n- 💰 **Cost Estimation**: Dynamic SOL cost predictions based on priority fees\n- 🔒 **Safe**: Prevents double-spending and tracks all operations\n- 📁 **CSV-based**: Simple recipient list management\n- 🧪 **Test Mode**: Use `--limit` to test with small batches before full runs\n- 💸 **Fee Optimization**: Calculates actual costs based on your priority fee settings\n\n\n## Installation\n\n```bash\ncargo build --release\n```\n\n## Workflow\n\n```mermaid\ngraph TD\n    A[Prepare CSV] --\u003e B[Run Distribution]\n    B --\u003e C{Interrupted?}\n    C --\u003e|Yes| D[Run Again - Auto Resume]\n    C --\u003e|No| E[Complete]\n    D --\u003e B\n```\n\n## Quick Start\n\n1. **Prepare your recipient list** (CSV format):\n```csv\nrecipient,amount\nEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v,1000000000\nSo11111111111111111111111111111111111111112,2000000000\n```\n\n2. **Run distribution**:\n```bash\n./target/release/spl-dropper distribute \\\n  --input-csv recipients.csv \\\n  --mint \u003cTOKEN_MINT\u003e \\\n  --from \u003cSOURCE_TOKEN_ACCOUNT\u003e \\\n  --owner owner.json \\\n  --fee-payer payer.json \\\n  --url https://api.mainnet-beta.solana.com \\\n  --priority-fee 20000\n```\n\nFor testing with a small batch first:\n```bash\n./target/release/spl-dropper distribute \\\n  --input-csv recipients.csv \\\n  --mint \u003cTOKEN_MINT\u003e \\\n  --from \u003cSOURCE_TOKEN_ACCOUNT\u003e \\\n  --owner owner.json \\\n  --fee-payer payer.json \\\n  --url https://api.mainnet-beta.solana.com \\\n  --priority-fee 20000 \\\n  --limit 5 \\\n  --dry-run\n```\n\n3. **Monitor progress**: The tool shows real-time progress and saves state automatically.\n\n## Key Commands\n\n### Distribute Tokens\n```bash\nspl-dropper distribute [OPTIONS]\n```\n\nOptions:\n- `--input-csv`: Path to CSV with recipients\n- `--mint`: SPL token mint address\n- `--from`: Source token account\n- `--owner`: Owner keypair (controls source account)\n- `--fee-payer`: Fee payer keypair\n- `--url`: RPC URL\n- `--rate-limit`: Requests per second (default: 10)\n- `--priority-fee`: Priority fee in microlamports per CU (default: 1000)\n- `--limit`: Limit number of recipients to process (useful for testing)\n- `--dry-run`: Preview distribution without executing\n- `--skip-ata`: Skip ATA creation checks\n- `--yes`: Skip confirmation prompt\n- `--force-clear-pending`: Force clear pending transactions (use if manually verified)\n\n### Generate Test Recipients\n```bash\nspl-dropper generate-recipients \\\n  --count 1000 \\\n  --amount 1000000000 \\\n  --output test_recipients.csv\n```\n\n\n## State Management\n\nThe tool automatically tracks distribution state in `.spl-dropper-state/\u003chash\u003e/` directories:\n- Each unique CSV+mint combination gets its own state\n- Automatic resume on interruption\n- Prevents accidental re-processing\n\n### Progress Tracking\n\nThe tool provides clear progress information:\n```\n📊 Progress: 5/973 recipients already completed\n📊 Processing recipients 6 to 10 (limiting to 5 out of 968 remaining)\n```\n\nWhen distribution completes:\n```\n✅ Distribution complete!\nTotal progress: 10/973 recipients completed\nThis run: 5 recipients processed\n```\n\n## Safety Features\n\n- **Balance Checks**: Prevents starting distributions without sufficient tokens\n- **Duplicate Prevention**: Tracks completed recipients\n- **Transaction Monitoring**: Handles confirmations and expirations\n- **Atomic State Updates**: Single-writer pattern prevents corruption\n\n## Cost Estimation\n\nRun with `--dry-run` to see detailed cost breakdown:\n- ATA creation costs (one-time): 0.00203928 SOL per account\n- Transaction fees: Base fee (0.000005 SOL) + Priority fee\n- Priority fees: Calculated as `priority_fee × 200,000 CU / 1e15`\n\nExample with different priority fees:\n- `--priority-fee 10000`: ~0.000007 SOL per transaction\n- `--priority-fee 20000`: ~0.000009 SOL per transaction\n- `--priority-fee 50000`: ~0.000015 SOL per transaction\n\n## Using the --limit Parameter\n\nThe `--limit` parameter is perfect for:\n- Testing your setup before a full mainnet run\n- Processing large airdrops in smaller, manageable batches\n- Verifying transaction costs with real transactions\n\nExample workflow:\n```bash\n# Test with 5 recipients\n./target/release/spl-dropper distribute ... --limit 5 --dry-run\n\n# Process first 10\n./target/release/spl-dropper distribute ... --limit 10 --yes\n\n# Process next 50 (automatically skips completed)\n./target/release/spl-dropper distribute ... --limit 50 --yes\n\n# Process all remaining\n./target/release/spl-dropper distribute ... --yes\n```\n\n## Performance\n\n- Processes in batches of 10 transfers per transaction\n- Configurable rate limiting\n- Automatic retry for failed/expired transactions\n- Typical throughput: 100-500 recipients/minute\n\n## Development\n\nRun tests:\n```bash\ncargo test\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalletconnect%2Fspl-dropper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwalletconnect%2Fspl-dropper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalletconnect%2Fspl-dropper/lists"}