{"id":18740503,"url":"https://github.com/vincelwt/super-provider","last_synced_at":"2025-04-12T20:05:14.092Z","repository":{"id":65359765,"uuid":"561691337","full_name":"vincelwt/super-provider","owner":"vincelwt","description":"Ethers.js meta-provider designed for optimal speed and reliability.","archived":false,"fork":false,"pushed_at":"2022-11-24T10:31:36.000Z","size":39,"stargazers_count":28,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-12T20:05:07.361Z","etag":null,"topics":["ethereum","ethersjs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vincelwt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-11-04T09:13:21.000Z","updated_at":"2024-08-13T22:39:28.000Z","dependencies_parsed_at":"2023-01-22T05:46:40.189Z","dependency_job_id":null,"html_url":"https://github.com/vincelwt/super-provider","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincelwt%2Fsuper-provider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincelwt%2Fsuper-provider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincelwt%2Fsuper-provider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincelwt%2Fsuper-provider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vincelwt","download_url":"https://codeload.github.com/vincelwt/super-provider/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625493,"owners_count":21135513,"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","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":["ethereum","ethersjs","typescript"],"created_at":"2024-11-07T15:39:30.268Z","updated_at":"2025-04-12T20:05:14.070Z","avatar_url":"https://github.com/vincelwt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://alt0.io/superprovider.svg\" /\u003e\n\u003c/p\u003e\n\nUsed by [alt0.io](https://alt0.io) to provide highly reliable and fast chain listening.\n\n### How it works\n\n- You supply it with a list of regular providers\n- It will frequently benchmark (with `getBlockNumber`) the providers supplied and rank them by response time. Providers lagging in blocks won't be used.\n- Depending on the selected mode, calls are either:\n  - spread in cycles between the fastest providers (default)\n  - sent to the fastest providers in parallel and the first response is returned (fastest)\n- If any call fails or stalls, it is retried on another provider with an exponential backoff.\n\n## Installation\n\n```bash\nnpm install ethers-super-provider\n```\n\n## Example Usage\n\n```typescript\nimport { SuperProvider } from \"ethers-super-provider\"\n\nimport { ethers } from \"ethers\"\n\nconst rpcs = [\n  \"https://api.mycryptoapi.com/eth\",\n  \"https://cloudflare-eth.com\",\n  \"https://eth-mainnet.public.blastapi.io\",\n  \"https://rpc.ankr.com/eth\",\n]\n\nconst provider = new SuperProvider(rpcs.map((url) =\u003e new ethers.providers.JsonRpcProvider(url)))\n\nconst blockNumber = await provider.getBlockNumber()\nconsole.log(blockNumber)\n```\n\n## API\n\n### `new SuperProvider(providers: Provider[], chainId: number, options?: SuperProviderOptions)`\n\n- `providers`: Array of providers to use\n- `chainId`: Chain ID to use (default: 1 / eth mainnet)\n- `options`: Options for the super provider\n\n### `options`\n\n- `mode`: Mode to use for calls. Either `spread` or `parallel`. Default: `spread`\n- `maxRetries`: Maximum number of retries for a call. Default: `3`\n- `benchmarkFrequency`: Interval between benchmarks. Default: `200000` (~3 minutes)\n- `acceptableBlockLag`: Maximum number of blocks a provider can lag behind the fastest provider. Default: `0`\n- `benchmarkRuns`: Number of runs for each benchmark. Default: `2`\n- `stallTimeout`: Timeout for a call to be considered stalled. Default: `4000` (4 seconds)\n- `maxParallel`: Maximum number of parallel calls. Default: `3`\n\n### Which mode to use?\n\n- if you are not doing very frequent calls and/or want the absolute fastest results, regardless of network use or cost, use `parallel` which will send the request to many providers in parallel and return the first available response.\n\n- for all other uses (espsecially if you are doing a lot of requests at once) use `spread` (default) which is more efficient. Limit expensive API calls to a provider. This is also more respectful for public providers as it won't flood them with requests you won't use.\n\n## Caveats\n\n- Currently doesn't support subscriptions \u0026 listening to events with `.on()`. PR welcome.\n- Doesn't have a concept of quorum and doesn't compare results.\n- Lots of untested edge cases.\n\n## Credit\n\nInspiration taken from ethers's [FallbackProvider](https://docs.ethers.io/v5/api/providers/other/), essential-eth's [FallthroughProvider](https://github.com/dawsbot/essential-eth/blob/master/src/providers/FallthroughProvider.ts) and Chainlist's [auto RPC benchmarking](https://chainlist.org/chain/1).\n\n## Used by\n\n- [alt0.io](alt0.io)\n\n## Author\n\nplz follow me [on twitter](https://twitter.com/vincelwt) I don't have many followers\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvincelwt%2Fsuper-provider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvincelwt%2Fsuper-provider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvincelwt%2Fsuper-provider/lists"}