{"id":51130768,"url":"https://github.com/anders94/usdc-speedtest","last_synced_at":"2026-06-25T12:01:27.576Z","repository":{"id":339477592,"uuid":"1161998689","full_name":"anders94/usdc-speedtest","owner":"anders94","description":"Benchmark EVM network throughput by sending USDC transfers in parallel.","archived":false,"fork":false,"pushed_at":"2026-03-05T16:42:28.000Z","size":94,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-05T19:31:59.273Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/anders94.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-19T18:58:47.000Z","updated_at":"2026-03-05T16:42:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anders94/usdc-speedtest","commit_stats":null,"previous_names":["anders94/usdc-speedtest"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/anders94/usdc-speedtest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Fusdc-speedtest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Fusdc-speedtest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Fusdc-speedtest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Fusdc-speedtest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anders94","download_url":"https://codeload.github.com/anders94/usdc-speedtest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Fusdc-speedtest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34773843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"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":"2026-06-25T12:01:26.997Z","updated_at":"2026-06-25T12:01:27.556Z","avatar_url":"https://github.com/anders94.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# usdc-speedtest\n\nBenchmark EVM network throughput by sending USDC transfers in parallel.\n\nDerives deterministic wallet pairs from a master key, funds them, runs back-and-forth USDC transfers across N parallel testers, and reports throughput and latency statistics.\n\n## Quick Start\n\n```bash\nnpm install\nnpm run build\n\n# Set your master wallet private key\nexport PRIVATE_KEY=0x...\n\n# Run with defaults (Base Sepolia, 5 testers, 60s)\nnpx usdc-speedtest\n\n# Or link globally so `usdc-speedtest` works anywhere\nnpm link\nusdc-speedtest\n\n# Or run directly without installing\nnode dist/cli.js\n```\n\n## How It Works\n\n1. **Derive wallets** — deterministically generates 2N wallets (N pairs) from the master key using BIP-44 HD derivation (`m/44'/60'/0'/0`)\n2. **Fund wallets** — sends ETH (for gas) and USDC ($0.01 per sender) from the master wallet to each derived wallet\n3. **Run test** — each tester ping-pongs $0.01 USDC between its wallet pair for the configured duration\n4. **Report stats** — aggregates throughput (tx/s), latency percentiles (p50/p95/p99), and gas usage\n5. **Cleanup** — optionally sweeps all funds back to the master wallet\n\n## CLI Options\n\n```\nusdc-speedtest [options]\n\nOptions:\n  -n, --network \u003cname\u003e      Network name (default: \"baseSepolia\")\n  -p, --parallel \u003ccount\u003e    Number of parallel testers (default: \"5\")\n  -d, --duration \u003cseconds\u003e  Test duration in seconds (default: 60, or 1800 with --traffic-shape)\n  --traffic-shape           Vary load over time using a random traffic curve\n  --rpc \u003curl\u003e               Override RPC endpoint\n  --usdc-address \u003caddr\u003e     Override USDC contract address\n  --chain-id \u003cid\u003e           Override chain ID\n  --cleanup                 Sweep funds from derived wallets back to master\n  --skip-funding            Skip the wallet funding step\n  --seed-gas \u003caddress\u003e      Seed a target address with RUSD (Radius only)\n  --seed-rounds \u003cn\u003e         Number of seed-gas iterations (Radius only - default: 10)\n  -h, --help                Display help\n```\n\n## Environment\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `PRIVATE_KEY` | Yes | Master wallet private key (hex, with or without `0x` prefix) |\n\nCreate a `.env` file in the project root or set it in your shell. The master wallet needs enough ETH for gas and enough USDC to fund sender wallets.\n\n## Supported Networks\n\n| Network | Flag | Chain ID | Block Time |\n|---------|------|----------|------------|\n| Ethereum Mainnet | `mainnet` | 1 | ~12s |\n| Ethereum Sepolia | `sepolia` | 11155111 | ~12s |\n| Base | `base` | 8453 | ~2s |\n| **Base Sepolia** | `baseSepolia` | 84532 | ~2s |\n| Radius | `radius` | 723 | ~0.5s |\n| Radius Testnet | `radiusTestnet` | — | ~0.5s |\n\nFor networks without built-in configs (or custom chains), use `--rpc`, `--usdc-address`, and `--chain-id` overrides.\n\n## Batch Funding via Disperse.app\n\nWhen the [Disperse.app](https://disperse.app) contract is detected on the target chain, funding is batched into 3 transactions regardless of wallet count:\n\n| Step | Transaction | Description |\n|------|-------------|-------------|\n| 1 | `disperseEther()` | Batch ETH to all wallets in one tx |\n| 2 | `approve()` | Approve Disperse to spend USDC |\n| 3 | `disperseToken()` | Batch USDC to all sender wallets in one tx |\n\nIf Disperse is unavailable (e.g. a new chain), the tool falls back to individual transactions with nonce pipelining.\n\n## Examples\n\n```bash\n# Base Sepolia, 10 parallel testers, 2 minutes\nusdc-speedtest -n baseSepolia -p 10 -d 120\n\n# Ethereum mainnet, 3 testers, 30 seconds\nusdc-speedtest -n mainnet -p 3 -d 30\n\n# Custom RPC and USDC address\nusdc-speedtest --rpc https://my-rpc.example.com --usdc-address 0x... --chain-id 12345\n\n# Traffic shaping: ramp load up and down over 30 minutes\nusdc-speedtest --traffic-shape -p 4\n\n# Traffic shaping with custom duration\nusdc-speedtest --traffic-shape -p 4 -d 120\n\n# Sweep all funds back to master wallet\nusdc-speedtest --cleanup\n\n# Seed a Radius address with RUSD (5 rounds)\nusdc-speedtest -n radius --seed-gas 0xTARGET --seed-rounds 5 --rpc https://rpc.radiustech.xyz/...\n```\n\n## Traffic Shaping\n\nThe `--traffic-shape` flag runs a longer test where throughput varies over time following a randomly generated curve. This is useful for testing how chains handle autoscaling under fluctuating load.\n\nWhen enabled, a random sequence of waypoints is generated (e.g. 25% → 77% over 2min → 16% over 5min → 50% over 1min). Each tester uses probabilistic throttling to match the current target — at 50% target, testers proceed roughly half the time; at 10%, they mostly wait. The curve is logged before the test starts and the spinner shows the current target percentage in real time.\n\nWithout `-d`, duration defaults to 1800s (30 minutes) to give the curve enough time to exercise a range of load levels.\n\n## RUSD Seeding (Radius)\n\nOn Radius, the native gas token (RUSD) is created by an automatic \"turnstile\" that converts SBC (an ERC-20) into RUSD ~$0.10 at a time, triggered whenever a transaction needs more RUSD than is available. The `--seed-gas` mode exploits this to accumulate RUSD on a target address.\n\nEach round:\n1. Queries the master wallet's actual RUSD balance via `rad_getBalanceRaw()`\n2. Sends available RUSD to the target as a native transfer\n3. Sends 1 wei of SBC to the target, which triggers the turnstile and refills ~$0.10 RUSD on master\n4. Repeats\n\nThe loop stops early if SBC balance is too low or RUSD is dust. A summary table is printed at the end.\n\n## Development\n\n```bash\nnpm install\nnpm run dev          # Run directly via tsx\nnpm run build        # Build to dist/\n```\n\n## Project Structure\n\n```\nsrc/\n  cli.ts                  Entry point and argument parsing\n  config/networks.ts      Network definitions\n  wallet/derive.ts        HD wallet derivation and pairing\n  wallet/fund.ts          Balance checks, funding plan, Disperse batching\n  test/runner.ts          Parallel test orchestration, Ctrl+C handling\n  test/tester.ts          Single tester: ping-pong USDC between wallet pair\n  test/traffic-curve.ts   Random traffic curve generation and interpolation\n  test/stats.ts           Statistics computation and display\n  radius/seed-gas.ts      RUSD seeding loop for Radius\n  cleanup/sweep.ts        Sweep USDC and ETH back to master\n  utils/usdc.ts           ERC-20 ABI and USDC helpers\n  utils/disperse.ts       Disperse.app contract detection and helpers\n  utils/prompt.ts         Interactive confirmation prompts\n  utils/logger.ts         Formatted console output\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanders94%2Fusdc-speedtest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanders94%2Fusdc-speedtest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanders94%2Fusdc-speedtest/lists"}